Skip to content

OEM tracking and AI outcome collection

OEM licenses and results are attributed to a partner without requiring an end-customer account. This is an additive extension of local API 1.0 and the existing C ABI. Use a runtime containing the telemetry extension; the earlier stock pilot ZIP does not contain it.

What appears in the portal

Open OEM Tracking at /portal/superadmin/oem as a platform administrator, or /portal/partner/oem in the active partner workspace. Select a stock pool and a 7/30/90-day receipt window. The page shows:

  • stock capacity, allocated/remaining rights, pool status and device term;
  • paginated device references, license start/end and last cloud contact;
  • successful/failed jobs, disk cleaned, RAM freed across runs and estimated energy;
  • recent outcomes and the number of AI samples awaiting review.

The platform administrator sees all pools; a partner sees only its current server-resolved workspace. A query parameter cannot change that workspace. Device license secrets, CPU/MAC identifiers and raw AI sample features are not included in portal reports. Up to 100 pools and the latest 100 outcomes are shown; devices paginate in groups of 100. A revoked pool's devices remain visible as revoked. Pausing a pool stops new activations while previously issued device terms remain valid.

Results are reported by the licensed device, not independently certified benchmarks. RAM totals add individual runs and do not represent unique installed memory. Energy is an estimate. Last contact is an upload timestamp, not proof that a device is currently online. Report windows use server receipt time; events also retain their original occurrence time.

Automatic reporting

The OEM host starts a separate non-blocking cloud uploader. Stock activation and the normal local job API are unchanged. Terminal scan/optimization/cancellation events enter the SQLite cloud outbox in the same transaction as the local job result. Only summary fields are copied; file paths, process names and contents are excluded. A small hourly heartbeat is queued while a stock license is configured.

The uploader uses the device's current OEM stock key and hardware binding at POST /license/oem-stock/telemetry. The server derives pool, partner, protocol and device reference from the actual stock claim and checks current expiry/revocation. The pool activation capability is not a telemetry credential. No portal/admin token is distributed. Legacy manually issued OEM keys remain usable for their existing local functions; automatic cloud tracking in this extension requires an OEM stock key.

Network errors and temporary denials retry with capped backoff. Pending data survives restart and remains bound to the license that created it; replacing the key cannot reattribute it to another partner. Duplicate receipts cannot count the same job again. Schema/conflicting-event errors are marked dead. Pending uploads expire locally after 29 days, below the server's 30-day occurrence window. A future-dated device clock must be corrected before rejected events can be resubmitted with a new, accurate record.

Read GET /v1/status through the DLL's existing generic request method. cloud_delivery provides enabled state, pending/sent/dead counts and a sanitized last error. webhook_delivery is independent. The existing partner webhook continues to deliver to the partner endpoint and is not the central telemetry transport.

AI samples require two permissions

Normal cleanup metrics are not AI training examples. Continuous autonomous OEM AI scheduling remains deferred. This extension provides a collection contract for a partner integration that actually observes an AI decision and its outcome:

  1. A platform operator explicitly enables the stock pool with PATCH /web/admin/oem-stock/pools/{pool_id}/telemetry-policy, body {"ai_training_enabled":true}. This uses an authorized portal API bearer and is never called by the client.
  2. Start the OEM host with HC_OEM_AI_TRAINING_CONSENT=1 after obtaining the required permission in the partner integration. The default is disabled. Each submitted sample must also contain consent:true.
  3. After a successful optimization for the current license, submit the measured sample below to POST /v1/telemetry/ai-outcomes through the authenticated local API. The caller's stable event ID makes a repeated request idempotent.
{
  "event_id": "11111111111111111111111111111111",
  "job_id": "22222222222222222222222222222222",
  "sample": {
    "consent": true,
    "action": "mem_clear",
    "model_version": "partner-policy-1",
    "before": {"cpu_percent": 30, "memory_percent": 70},
    "after": {"cpu_percent": 25, "memory_percent": 60},
    "elapsed_seconds": 10
  }
}

These values are an illustrative request, not measured HeimerClean performance. Use the actual completed job_id, a random 32-character lowercase hexadecimal event ID, actual observations and model version. Allowed actions: temp_clear, mem_clear, noop, daily_optimization. Unknown fields, paths, model weights, non-finite/out-of-range numbers, missing consent and unrelated/incomplete jobs are rejected. The runtime never invents samples from a cleanup score.

Samples enter a separate pending_review category in the OEM collection. Attribution establishes the license source; it cannot prove that a compromised client supplied genuine measurements. No sample is automatically trusted, trained on, exported into the standard desktop dataset, or used to publish a model. Validation/curation and an approved model-training run remain separate work. Disabling pool collection rejects further sample uploads; disabling local collection on restart stops queued sample uploads too. Previously received records expire under the retention policy.

Bounds and retention

  • Cloud body: 64 KiB maximum; up to 50 events per request. Current uploader sends one event at a time.
  • Device upload allowance: 2,000 attempted events per UTC day, including replays; bounded peer/device rate limits also apply.
  • Local pending queue: 10,000 entries; overflow/dead status remains observable without blocking cleanup. At most 1,000 terminal delivery records are retained locally for 30 days.
  • Cloud outcomes and AI samples expire 90 days after receipt. Presence expires after 365 days without upload. License stock/term records are separate and do not expire with telemetry.
  • Cloud reads: OEM stock and tracking OpenAPI. Local SDK routes: local OpenAPI.

The OEM client must still use the documented production HTTPS endpoint and protected local configuration. A local administrator can inspect a client process; no embedded capability is promised to be unextractable.