Skip to content

feat(spec): freeze attachment v1 contract - #675

Draft
nik13 wants to merge 4 commits into
devfrom
feat/attachments-contract
Draft

nik13 wants to merge 4 commits into
devfrom
feat/attachments-contract

Conversation

@nik13

@nik13 nik13 commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

Part of TH-2379 (Linear).

Summary

Freeze F01: fi.attachments.v1 in spec/attachments/v1/, without adding an SDK uploader, recorder, backend implementation or product UI.

  • Closed JSON Schema and OpenAPI 3.1 for bootstrap, upload/import, scoped occurrences, recording manifests, narrow write capabilities and authenticated playback.
  • Bounded span references, exact trace identity, nonsecret writer correlation and occurrence-based resolution.
  • Executable deny-wins privacy/security tables and shared language-neutral fixtures. Attachments and creation of new recordings remain separately off; hide/PII rules win.
  • Reference validators, synthetic HTTP tests and network-isolated CI. No runtime package or existing semantic-convention default changes.

Explicit media-session binding amendment

Latest contract revision: f0d52e7. This remains an unreleased, contract-only draft, not backend/UI implementation or release readiness. The sections below retain the earlier completed-recording amendment and its historical evidence.

The previous draft combined fresh random cookies at one shared path with implicit newest-row selection. Concurrent exchanges could overwrite the cookie or select a different session, including equal-expiry rows; the exact-binding gateway then correctly denied otherwise authorized playback. This is a concurrency/availability defect, not evidence of unauthorized access.

  • Exchange stays authenticated 204, without a body, and adds non-secret X-Attachment-Media-Session UUID and X-Attachment-Media-Expires-At headers.
  • Random secrets remain exclusively in host-only Secure/HttpOnly/SameSite=Strict fi_media_session_v2 cookies at /tracer/v1/attachment-media/{media_session_id}/, with digest-only persistence.
  • Resolve requires the exact handle, explicit application bearer and exact Origin; authorizes the original user/access-token row/organization/expiry/revocation; and never falls back to a latest row.
  • Gateway paths contain session/occurrence/grant. Route session, cookie-derived row and grant FK must agree. Existing parent, occurrence, scope, representation, policy, retention, deletion and streaming checks remain mandatory.
  • Fixed expiry and independent session cookies permit overlap during renewal; no revoke-on-every-exchange or shared mutable latest selector. Gated cutover invalidates legacy rows once, rejects old-parent cookies and missing-handle issuance, and requires coordinated client reload. No migration or recoverable-secret storage is requested.

Security wording reflects source inspection: these issuance adapters require application bearer identity; exchange bypasses Django token-CSRF enforcement. The amendment requires exact Origin on resolve too, does not claim X-CSRFToken is enforced, and does not enable cookie-only application authentication or loosen other enforced controls. Original access-row revocation is tested in the fixture oracle. Post-refresh logout does not automatically revoke pre-refresh access rows under existing authentication policy; that inherited limitation remains a separate security/release item, not a solved token-family change.

Canonical OpenAPI, strict session-path validation (maximum 230 characters), header projections, wire/security fixtures, normative renewal/cutover notes and contract tests are updated together. A fingerprint regression preserves every prior schema definition except the deliberately amended ResolveResult; four media wire definitions are added. No application code, UI, SDK or migration changes; product vendored copies remain untouched.

Latest cloud evidence

Exact-head attachment conformance passed on existing Ubuntu 24.04 CI, with fixture/unit tests network-isolated and HTTP tests loopback-only:

623 shared fixtures: privacy 82, security 217, wire 170, identity 11,
  scope 9, lifecycle 7, recording_import 46, media_session 81
28 contract unit tests: OK
6 synthetic HTTP protocol tests: OK

Coverage includes bodyless 204/header exchange, required well-formed selectors, exact route syntax, distinct same-name cookie paths, wrong/missing user/access-row/org/handle combinations, route/cookie/grant mismatches, legacy-cookie rejection, fixed deadlines, original-row revocation across request forms, and nonexposure of media secrets. The first cloud run caught a missing resolve-specific security-table predicate; the follow-up commit added that predicate and the exact final head passed. No tests/builds/installs ran on the laptop; no staging VM was created, so no task VM remains to delete.

These are schema, synthetic-row, stdlib cookie-jar and loopback tests—not browser concurrency proof. Integrated backend/UI qualification still owes reversed initial exchanges, interleaved resolves, equal expiries, independent tabs/orgs, renewal during active playback/Range/streaming, auth/org changes, cookie eviction, deletion and seek/play continuity.

Consumers must pin the exact revision above, re-copy spec/attachments/v1/contract.schema.json byte-for-byte into their vendored F01 schema, update the provenance pin, implement the documented adapters, and use their existing backend OpenAPI/frontend generation commands. Do not hand-edit generated or vendored copies, infer affinity by sorting, or bypass unrelated API surface checks.

Blocking review correction

Commit f3b0923 separates completed whole-recording admission from upload/segment admission.

POST /imports retains the existing {upload, source} form and adds the disjoint {mode: "completed_recording", recording, source} form. The new descriptor declares an exact whole-source byte length and duration, with a registered recording identity and authorized parent. It returns a recording job, not a larger upload capability. A content-free scoped GET /imports/{job_id}/status contract accompanies it.

The normative protocol specifies:

  • Terminal completed, immutable, authorized provider outputs or private envelopes only; no new recorder or billable Egress startup.
  • Whole-source admission within negotiated recording byte/duration limits. Reserve the full staged source plus a bounded output window under project, organization and global capacity.
  • Sequential version-pinned source ranges no larger than min(max_upload_bytes, segment_bytes), bounded buffers/timeouts/retries, and exact counted length/duration enforcement. A connector lacking bounded immutable-range semantics is unsupported, not an unbounded-download fallback.
  • Independently playable server-produced segments bounded by both byte and duration ceilings, including container overhead. The source and aggregate segment output each fit the recording budget; decoded/derivative work has separately reserved finite bounds.
  • Full validated manifest coverage, exact scoped segment binding, atomic publication, and cleanup/deletion fencing. Private storage and authenticated occurrence playback remain mandatory.

The existing UploadRequest, negotiated Limits, privacy table and security table are unchanged, verified against the reviewed baseline. This does not increase the 50 MiB standalone upload or 8 MiB segment ceilings. A maximum-envelope source must still leave staging headroom under the reservation ceiling.

Cloud verification

Executed the baseline and exact committed Git archive on a temporary private GCP VM with Debian 12, Python 3.11.2, jsonschema==4.23.0 and openapi-spec-validator==0.7.2. No local tests, builds, installs or stacks. The VM had no external address or service account, was reached via IAP and had automatic deletion expiry. It was explicitly deleted; the subsequent exact-name listing was empty.

Exact candidate commands from the cloud runner (disposable test directories):

sudo unshare --net -- /tmp/att-contract-fix-venv/bin/python -I /tmp/att-contract-fix-source/spec/attachments/v1/validate.py
sudo unshare --net -- /tmp/att-contract-fix-venv/bin/python -I /tmp/att-contract-fix-source/spec/attachments/v1/test_contract.py
sudo unshare --net -- bash -c 'ip link set lo up; exec "$@"' bash /tmp/att-contract-fix-venv/bin/python -I /tmp/att-contract-fix-source/spec/attachments/v1/test_protocol.py

Final committed-archive result, exit 0:

504 shared fixtures:
  privacy 82, security 210, wire 139, identity 11,
  scope 9, lifecycle 7, recording_import 46
21 unit tests: OK
4 synthetic HTTP protocol tests: OK

The baseline aeed09f2 was rerun in the same isolated environment: 430 fixtures, 16 unit tests and 3 protocol tests passed. An independent old/new admission probe confirmed that five-minute and one-hour whole recordings fail the old admission form, succeed in the new completed-recording form, and still fail as oversized segments. The committed regression test pins that distinction.

The synthetic PCM regression actually creates a 172,800,044-byte one-hour 24-kHz mono s16 WAV, reads it with bounded buffers, and produces 120 independently readable 30-second WAV segments, 1,440,044 bytes each. Total output is 172,805,280 bytes, including all segment headers. Independent segment decoding preserves the PCM SHA-256:

8783f7ad2bc59e3d4289f1037a88cac51ee64f72680facb523e076d2e1412d9c

The 46 new import fixtures include short/excess source lengths, changed generation, ignored or incomplete ranges, negotiated byte/duration limits, segment output expansion, full scope/resource headroom, over-budget denial before the synthetic read boundary, malformed manifests and mixed-source ancestry. Existing removal negative controls still cover every privacy/security predicate.

All 18 contract file hashes match the committed files tested on the VM. Final VM log SHA-256:

8d22e33af2f3c096f7c29ad51d32f99c93a4b9d155f19d118ac25d096d4d9ced

The first candidate run caught a new fixture's incorrect separate-track layout. Its failed log is preserved; the fixture was corrected to the intended mixed timeline, then the full suite passed twice, including the final committed archive.

CI on f3b0923c: 7 successful checks, 4 conditionally skipped package-matrix jobs, no failures/pending checks. Attachment v1 conformance run.

Scope and consumer coordination

This remains a contract-only draft. The WAV segmenter and HTTP receiver are explicitly test doubles, not production importer, authorization, storage or codec qualification. Real provider/Egress handoff, reservation concurrency, storage denial, decoder isolation, session capture, playback and Q01/Q02 integration are owned by the implementation lanes. No operation is marked capture-supported here.

Consumers must pin the updated contract commit and adopt the new recording-import request/response and status route. Existing single-attachment requests remain valid. Product API owners must generate their full backend contracts when implementing these schemas. There are no product migrations, frontend changes, deployments or feature enablement in this PR, and no applicable root/spec Ruff configuration.

E2E coverage

not applicable (no e2e/ harness) · flows hit: n/a · marker: n/a · verdict: not applicable. This PR adds no user-visible implementation.

🤖 Generated with Claude Code

nik13 and others added 2 commits November 10, 2026 16:19
Define neutral schemas, deny-wins conformance tables, and shared fixtures for the feature-off Python voice foundation. Include schema, negative-control, and synthetic HTTP validators without runtime SDK or backend implementation.

Co-Authored-By: Claude Code <noreply@anthropic.com>
Define a completed-recording job with exact source declarations, immutable bounded reads, scoped reservations and server-produced segments. Preserve single-upload and segment ceilings; cover source-length and resource-bound failures with shared fixtures and a one-hour synthetic WAV regression.

Co-Authored-By: Claude Code <noreply@anthropic.com>
nik13 and others added 2 commits November 14, 2026 21:28
Amend the unreleased wire contract with non-secret exchange headers, exact resolve selection, session-scoped v2 cookies and gateway identity equality. Preserve occurrence authorization and document bearer-mode Origin defenses and the inherited refresh/logout boundary. Add synthetic binding, cookie-path and wire conformance coverage; real browser qualification remains downstream.

Part of TH-2379 (Linear).

Co-Authored-By: Claude Code <noreply@anthropic.com>
The first cloud conformance run caught that the existing session-grant rule covered gateway reads only. Add a distinct deny-wins resolve selector rule, covered by the new missing/foreign binding fixtures, and report fixture IDs without payloads on conformance failure.

Co-Authored-By: Claude Code <noreply@anthropic.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant