Arc Forge Labs Docs v2026.10.2
Dictate

Arc Forge Backend Handoff v1

Status: WAVE 0 AUTHORITY LOCKED — DEPLOYMENT VERIFICATION UNKNOWN.

Wave 0 gate: PASSED — planning authority lock only. This handoff is the smallest Dictate-side request to the external active arc-forge-deck owner. It does not claim that source implementation or live routes conform to the Dictate Platform Contract v1. External owner response, deployment SHA, and live behavior remain later verification tasks and do not leave an implementation decision unresolved for independent Wave 1 work.

Repository boundary and evidence status

Dictate implementation stays in /home/samuel/repos/dictate on forge/dictate-pro-platform. Shared account, commerce, backend, Deck stabilization, deployment, and release ownership remains outside this lane in /home/samuel/repos/arc-forge-deck. This round makes no external-repository, Helm, live-system, or credential changes.

The external source snapshot supplied for review is arc-forge-deck@2ee29c9dbefb5208aea331042f56b8fad7112b4f on agent/deployment-harmony-phase2. The source implementation status is present at that revision; deployment verification is UNKNOWN. The release workflow's ability to emit a SHA is not evidence that these Dictate routes are deployed at that SHA.

Area Dictate branch owns Shared backend / Deck owner owns
Desktop Local-first UX, current /api gateway compatibility, local/explicit legacy /v1 compatibility, OS secret handling, sync client, hosted-job client, packaging, and Dictate tests —
Account platform Contract fixtures, client expectations, migration notes, and evidence Arc Forge account subject, browser sessions, desktop grants, refresh families, device authorization, canonical discovery, and return-to-Dictate behavior
Commerce and entitlement Dictate product mapping and client presentation Stripe/webhook authority, commerce projection, product=dictate, entitlement=dictate_pro, and policy states
Hosted gateway Dictate capability request and audio-second consumer Provider credential boundary, allowlists, shared middleware, STT adapter, usage event authority, and normalized errors
Sync and jobs Encrypted envelopes, opt-in behavior, local outbox, polling/retrieval client, and privacy UX Account-scoped devices, encrypted record/job APIs, durable workers, encrypted result artifacts, retention/deletion, and cross-account authorization

Locked proposed authority map

The contract's authority_map is the only machine-readable authority map. Each production surface has one proposed authority; UNKNOWN below is deployment verification status, not a second candidate or an open implementation choice.

Production surface One proposed authority Owner role Source status Deployment verification Disposition
Desktop/local compatibility dictate_desktop_client Dictate implementation lane Source present Not applicable /api current compatibility; /v1 local/explicit legacy only
Identity/auth/discovery arc_forge_shared_account_backend External shared backend owner Pinned candidate present UNKNOWN Durable Arc Forge account, email fallback, PKCE, device grant, refresh
Commerce/entitlement arc_forge_shared_commerce_backend External shared backend owner Pinned candidate present UNKNOWN Dictate checkout/webhook/projection; canonical canceled mapping
Devices/recovery arc_forge_shared_account_backend External shared backend owner Pinned candidate present; recovery route requires migration UNKNOWN Registration, consent/approval, recovery, revocation
Encrypted sync arc_forge_shared_backend_with_dictate_client_encryption External shared backend + Dictate client Contract locked; storage implementation pending UNKNOWN Client encrypts; backend owns durable envelopes/cursors
Hosted jobs/results arc_forge_shared_dictate_hosted_backend External shared backend owner Implemented locally on forge/wave1-durable-auth (6896fc4+) UNKNOWN deploy SHA Durable worker, server-managed encrypted artifact, ack/delete
Dictate usage arc_forge_shared_dictate_usage_ledger External shared backend owner Pinned candidate present; lifecycle extension required UNKNOWN Dictate audio-second ledger, separate from Deck
Provider-neutral STT gateway arc_forge_shared_provider_gateway External shared backend owner Direct provider source present; shared STT contract not proven UNKNOWN Governed provider request; server-only credentials
Dictate product surface dictate_desktop_and_dictate_product_ui Dictate implementation lane; Deck UI separate Source present Not applicable Local/Cloud execution copy; Dictate Pro remains paid offering

Smallest requested backend changes

  1. Canonical account discovery and login. Use the locked proposed origin https://console.arcforge.au and one neutral Arc Forge origin and make the discovery document advertise only HTTPS issuer, authorization, token, refresh, and device endpoints. The current live console.arcforge.au and deck.arcforge.au probes return 200 but advertise HTTP endpoints and land at Deck-branded /deck/login; those are migration evidence, not accepted production behavior.

  2. Durable desktop and browser authentication. Authorization grants, device-code records, and refresh families for Dictate desktop paths are implemented locally in DurableAuthStore (hashed SQLite). Browser login codes and portal_refresh cookies use AccountChallengeStore + PortalRefreshStore (hashed SQLite via portal_account_auth). Remaining ephemeral guards are labelled in residual_interim_auth.py and must not be claimed as credential authority.

  3. One neutral identity boundary. Make account_id the authenticated subject and ownership boundary. Keep product=dictate and entitlement=dictate_pro separate from the Arc Forge identity, with Dictate audio-second usage separate from Deck usage. Existing source candidates are arc-forge-deck@2ee29c9:src/arc_forge_console/models.py:100-112,363-375,409-431.

  4. Device authority. Provide account-scoped register, list, approve, and revoke operations. A revocation must affect refresh, sync, and hosted jobs consistently and return the reusable device state enum from the contract.

  5. Encrypted sync authority. Provide opt-in push/pull/cursor, key-envelope, export, and delete operations. The server may see only the contract's explicitly permitted envelope metadata and ciphertext; it must not turn raw audio or readable transcript text into normal sync data. Implement the contract's SyncEnvelope fields and per-record accepted/rejected/winner/ conflict outcomes so an offline outbox can drain page by page.

  6. Durable hosted job handoff. Make create/upload/status/result/ack/cancel worker-owned and restart-safe. Completion must persist before the worker responds; client polling must find the same server-managed encrypted artifact after a lost response; retrieval and acknowledgement must be idempotent; raw audio and readable result material must expire and be deleted after the tested lifecycle. Every result is the contract's mandatory HostedResultArtifact: versioned authenticated encryption or a bounded artifact reference, algorithm, recipient key, nonce, account/device/job/ artifact AAD and integrity binding, expiry, and delete-after-ack semantics.

  7. Governed gateway and exact usage. Route Dictate capabilities dictate.transcribe and dictate.transcribe_diarized through one agreed server-side gateway boundary. Each immutable usage event must carry event_id, account_id, product/capability, request/job/idempotency and correlation identifiers, period, event type, lifecycle, numeric amount and quantity in audio_seconds, and enough linkage for reserve, settle, and rollback. The gateway may carry audio bytes or a bounded artifact reference only at the governed provider request surface; provider/model aliases are server-selected and credentials remain server-only.

  8. Migrate source risks before acceptance. The pinned source has a direct xAI provider path and two audio-storage modes, and it persists/returns plaintext transcript text. These are migration findings, not claims that the source is deployed: arc-forge-deck@2ee29c9:src/arc_forge_console/config.py:161-175,573-599, arc-forge-deck@2ee29c9:src/arc_forge_console/provider_gateway.py:61-71,239-282, arc-forge-deck@2ee29c9:src/arc_forge_console/dictate.py:717-828,831-880,1197-1225, and arc-forge-deck@2ee29c9:src/arc_forge_console/models.py:526-540.

Canonical route agreement

The machine-readable contract's root operations object is the only canonical proposed route map. It is locked for independent implementation; the external owner later verifies deployment of that map and its HTTPS origin. This handoff does not create a second machine-readable route map.

Surface Contract operation IDs Owner decision
Discovery/email/browser/device auth account.discovery, account.email_code_start, account.email_code_verify, account.browser_consent, account.browser_consent_decision, account.token, account.device_authorize, account.device_approval HTTPS discovery, permanent email fallback, PKCE/browser consent, RFC device grant/polling, refresh rotation/reuse, and neutral Arc Forge return behavior
Entitlement, usage, and commerce entitlement.read, usage.read, commerce.read, commerce.checkout, commerce.webhook Shared account read authority, product filter, checkout/webhook projection, plan/state mapping, canonical canceled, and Dictate usage ledger
Devices and recovery device.register, device.list, device.approve, device.revoke, device.recovery_approve Device key binding, browser/device approval, current-device recovery, revocation propagation, and account isolation
Encrypted sync sync.push, sync.pull, sync.cursor, sync.key_envelopes.write, sync.key_envelopes.read, sync.export, sync.delete Opt-in, envelope encryption, cursor/conflict semantics, export, and cloud deletion
Hosted jobs hosted.create, hosted.upload, hosted.status, hosted.result, hosted.ack, hosted.cancel Durable worker, upload/processing TTL, inherited diarized capability, server-managed encrypted result envelope/reference, retry/ack/delete semantics
Shared gateway gateway.invoke Internal-only transport, provider policy, normalized errors, and usage ledger ownership

The current source route candidates are visible at arc-forge-deck@2ee29c9:src/arc_forge_console/dashboard.py:12632-12802,12807-13123,13125-13127 and arc-forge-deck@2ee29c9:src/arc_forge_console/dictate.py:1329-1638; they require reconciliation with the contract and are not deployed-route proof.

Surface-specific privacy data-flow matrix

This matrix is an acceptance contract, not a prose aspiration.

Surface Allowed surfaces Forbidden surfaces Lifetime/proof requirement
Provider credentials and server client secrets Server runtime secret boundary only Desktop client, browser payload, sync, logs, analytics, support exports Never client-visible; no public-native client secret
Access/refresh/auth/device tokens Auth protocol and secure native storage only Logs, sync, support exports, analytics, provider requests Protocol TTL, refresh rotation/revocation, and OS-backed storage
Hosted audio Explicit hosted upload, bounded processing worker, and governed provider request Normal sync, logs, analytics, support exports Upload/processing/provider-request TTL; delete on terminal outcome or expiry
Governed provider-request audio Governed server-side provider request only Desktop provider credentials, normal sync, logs, analytics, support exports Audio bytes or bounded artifact reference only; provider/model aliases are server-selected
Governed provider response Bounded gateway/worker memory and immediate server-managed encryption Persistence, logs, analytics, support exports, normal sync Request-scoped memory only; encrypt immediately, then delete readable provider response
Readable transcript Authenticated client delivery and server-managed encrypted result artifact Logs, analytics, support exports, normal sync Bounded artifact lifetime; delete after acknowledgement or TTL

The structured version of this matrix is data_flow_matrix.rows in the contract and must be used by implementation and proof tests. The contract also requires lost-response, worker-restart, duplicate-retrieval, retryable-ack, expiry/deletion, cross-account, and no-readable-support/log/analytics proofs.

Source implementation and migration risks

The pinned external source is useful evidence but is not yet the accepted production architecture:

  • DictateJob.status currently includes source values such as queued, uploaded, processing, ready, failed, and quota_exceeded; the v1 mapping is explicitly ready → completed and quota_exceeded → quota_rejected.
  • DictateUsageEvent currently has a primary event ID, account/job, billable seconds, and period, but not the full v1 immutable quantity/lifecycle and reserve-settle-rollback correlation contract.
  • local_spool writes request audio to a path; signed_object_upload is an alternate source mode. Neither is accepted without a deletion/TTL proof.
  • DictateTranscriptSegment.text is a plaintext source field and the current transcript route returns readable text. This must migrate to the bounded encrypted-result handoff.
  • arc-forge-deck@2ee29c9:src/arc_forge_console/provider_gateway.py:239-282 directly posts the Dictate audio to xAI using a server-side setting. arc-forge-deck@2ee29c9:src/arc_forge_console/litellm_gateway.py:83-240 is currently a Deck policy/chat-completion proof, not evidence of a Dictate audio production lane.

Deployment and acceptance gates

  • The external owner records the accepted contract revision and deploys only an image whose release metadata identifies the reviewed source revision. The source release lane emits git_sha/image metadata in arc-forge-deck@2ee29c9:src/arc_forge_console/release.py:9-19 and builds and deploys SHA-tagged images in arc-forge-deck@2ee29c9:.github/workflows/ci-deploy.yml:211-245,257-301,352-425. This is a gate to verify, not deployment evidence already satisfied.
  • Discovery and live smoke tests show HTTPS endpoints, neutral Arc Forge branding, return-to-Dictate behavior, and the accepted operation map.
  • Auth grants, refresh families, device records, jobs, usage events, and replay state survive process restart and rolling deploy.
  • All account, entitlement, commerce, device, sync, hosted, gateway, and usage reads/writes enforce account_id; Dictate and Deck usage remain separate.
  • Hosted jobs prove durable completion, lost-response polling, duplicate retrieval, idempotent acknowledgement, retry/cancel behavior, exact audio-second settlement/rollback, cross-account denial, and raw-audio/result deletion.
  • Privacy tests prove the matrix above for client payloads, secure storage, sync, logs, analytics, support exports, provider requests, and artifacts.
  • The local /v1 server remains explicitly non-production, and no released /v1 client count is claimed until an evidence source is supplied.

Later owner and deployment verification tasks

The Wave 0 gate is PASSED because the proposed authorities and contract are locked. The external active owner must still provide a versioned response and live evidence for these later verification tasks:

  • deployment of the canonical Arc Forge origin and the single contract operation map;
  • the source/deployment status for account, commerce, entitlement, device, sync, hosted-job, gateway, and usage authorities;
  • the durable store/worker/deletion design and all privacy proofs;
  • the governed provider/gateway path, including whether and how existing LiteLLM tooling is promoted for Dictate audio;
  • the source migration plan for plaintext transcript storage, direct provider access, current route compatibility, and the existing usage schema;
  • the accepted image/source revision and live deployment verification;
  • the bounded compatibility window for current /api clients and local or explicit legacy /v1 reference behavior.

Until that confirmation exists, this document and the v1 contract are Dictate-side authority/implementation inputs without a live-conformance claim. This round does not begin Wave 1 or authorize external repository, deployment, merge, or release changes.

Edit this page on GitHubMarkdownSource fe527b9