Repository navigation
Conversation
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>
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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Part of TH-2379 (Linear).
Summary
Freeze F01:
fi.attachments.v1inspec/attachments/v1/, without adding an SDK uploader, recorder, backend implementation or product UI.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.
X-Attachment-Media-SessionUUID andX-Attachment-Media-Expires-Atheaders.fi_media_session_v2cookies at/tracer/v1/attachment-media/{media_session_id}/, with digest-only persistence.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-CSRFTokenis 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:
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.jsonbyte-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 /importsretains 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 scopedGET /imports/{job_id}/statuscontract accompanies it.The normative protocol specifies:
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.The existing
UploadRequest, negotiatedLimits, 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.0andopenapi-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.pyFinal committed-archive result, exit 0:
The baseline
aeed09f2was 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:
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:
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