@capsiynau/intelligence-contracts 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aled Parry / Capsiynau
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,36 @@
+# @capsiynau/intelligence-contracts
+
+The wire contract between products and the Intelligence Layer: job statuses,
+error codes, capability and scope names, the segment model, event schemas.
+
+**Private.** Not published, and not publishable - `"private": true`. The
+published packages are a permanent public baseline (ADR 0028); this one is not
+part of it.
+
+## What belongs here
+
+Anything a client needs to speak the protocol: constants it branches on, shapes
+it exchanges, invariants it can assert.
+
+## What must never land here
+
+Provider implementations, prompts, model names, routing or fallback logic,
+quality-profile internals. The reading test (ADR 0006): a developer holding only
+this package and the client should be unable to rebuild the platform. If a type
+encodes *how* something is computed rather than *what* is exchanged, it belongs
+in the platform.
+
+## The additive rule
+
+Within a major version, a status, code, scope or capability may be **added**,
+never removed or repurposed. `scripts/check-contract-additive.mjs` fails the
+build on a removal, checked against `contract-baseline.json`.
+
+## Usage
+
+No workspace wiring - this repo consumes in-repo packages by relative path:
+
+```js
+import { JOB_STATUS, errorBody, validateTranslationRoundTrip }
+  from '../../packages/intelligence-contracts/src/index.js'
+```

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@capsiynau/intelligence-contracts",
+  "version": "0.1.0",
+  "description": "Wire contracts between products and the Intelligence Layer: job statuses, error codes, capability names, the segment model, and event schemas. Types and constants only - no implementation, no prompts, no provider names.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Aled Parry <aled@aledparry.com>",
+  "main": "./src/index.js",
+  "types": "./types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./jobs": "./src/jobs.js",
+    "./errors": "./src/errors.js",
+    "./capabilities": "./src/capabilities.js",
+    "./segments": "./src/segments.js",
+    "./events": "./src/events.js"
+  },
+  "files": [
+    "src",
+    "types",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "vitest run __tests__"
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aledprysparry/capsiynau-intelligence.git",
+    "directory": "packages/intelligence-contracts"
+  }
+}

package/src/capabilities.js

@@ -0,0 +1,118 @@
+/**
+ * @capsiynau/intelligence-contracts/capabilities
+ *
+ * Capability and quality-profile names (ADR 0003). A client asks for a
+ * capability at a quality profile and never learns which provider ran, which
+ * model, what the prompt said, or what the fallback order was - that is what
+ * lets the platform re-route, re-price or fall back without a client release.
+ *
+ * A profile is a public commitment about outcome and cost band. Adding one is
+ * cheap; changing what an existing one means is a breaking change.
+ */
+
+export const CAPABILITY = Object.freeze({
+  TRANSCRIPTION: 'transcription',
+  TRANSLATION:   'translation',
+  LANGUAGE:      'language',
+  CAPTIONS:      'captions',
+  GLOSSARY:      'glossary',
+  ANALYSIS:      'analysis',
+  SEARCH:        'search',
+  MEDIA:         'media',
+  LIVE:          'live',
+  // A human looking at a draft before it goes out. Not a provider capability -
+  // nothing is routed to a model - but a platform capability a client asks for
+  // by name, so it belongs in the same vocabulary (ADR 0003).
+  REVIEW:        'review',
+})
+
+export const ALL_CAPABILITIES = Object.freeze(Object.values(CAPABILITY))
+
+/** Capabilities that run as jobs. The rest answer synchronously. */
+export const ASYNC_CAPABILITIES = Object.freeze([
+  CAPABILITY.TRANSCRIPTION,
+  CAPABILITY.TRANSLATION,
+  CAPABILITY.ANALYSIS,
+  CAPABILITY.MEDIA,
+])
+
+export const QUALITY_PROFILE = Object.freeze({
+  FAST:            'fast',
+  ACCURATE:        'accurate',
+  WELSH_BROADCAST: 'welsh-broadcast',
+})
+
+export const ALL_QUALITY_PROFILES = Object.freeze(Object.values(QUALITY_PROFILE))
+
+/** Scopes a client credential may hold (ADR 0007). */
+export const SCOPE = Object.freeze({
+  TRANSCRIPTION_WRITE: 'transcription:write',
+  TRANSCRIPTION_READ:  'transcription:read',
+  TRANSLATION_WRITE:   'translation:write',
+  // Added 5.1 alongside the translation endpoint. Reads carry their own scope
+  // for the same reason transcription's do: a credential holding only
+  // `translation:write` could otherwise read every job status and result, and
+  // one whose write access had been revoked could still poll (Codex, #1505).
+  TRANSLATION_READ:    'translation:read',
+  CAPTIONS_ANALYSE:    'captions:analyse',
+  GLOSSARIES_WRITE:    'glossaries:write',
+  GLOSSARIES_READ:     'glossaries:read',
+  // Added 6.2 alongside the analysis endpoint. Split read from write for the
+  // same reason translation's are: a credential that may SUBMIT a transcript
+  // for summarising should not thereby gain the ability to read every analysis
+  // in the organisation - and a summary of a private meeting is a more
+  // sensitive artefact than the job that produced it.
+  ANALYSIS_WRITE:      'analysis:write',
+  ANALYSIS_READ:       'analysis:read',
+  SEARCH_QUERY:        'search:query',
+  // Added 6.3 alongside the search endpoint. Indexing writes documents into a
+  // tenant's corpus and spends embedding tokens; querying only reads it. A
+  // credential that may ASK should not thereby be able to WRITE what everyone
+  // else's answers are retrieved from - same split as every other capability.
+  SEARCH_INDEX:        'search:index',
+  // Added 6.5a alongside the media endpoint. Write submits provider-billed
+  // work; read polls it - same split as every job capability, for the same
+  // reason translation split them (#1505).
+  MEDIA_WRITE:         'media:write',
+  MEDIA_READ:          'media:read',
+  // Added 7.4a. The credential-management surface itself. OPERATOR-ISSUED
+  // ONLY: the admin endpoints refuse to grant this scope, so an admin
+  // credential cannot mint further admin credentials - the chain of custody
+  // for it always runs through issue-credential.mjs on an operator machine.
+  CREDENTIALS_ADMIN:   'credentials:admin',
+  ASSETS_WRITE:        'assets:write',
+  USAGE_READ:          'usage:read',
+  // Reviews split read from write for the same reason translation did: a
+  // credential that may CREATE a review for its own drafts should not thereby
+  // gain the ability to read every review in the organisation, including the
+  // drafts and the reviewer comments on them.
+  REVIEWS_WRITE:       'reviews:write',
+  REVIEWS_READ:        'reviews:read',
+})
+
+export const ALL_SCOPES = Object.freeze(Object.values(SCOPE))
+
+/**
+ * Neutral usage units (ADR 0022). The platform reports quantities; products
+ * apply their own pricing. No plan name, tier or price belongs in this file -
+ * that is the whole point of the boundary.
+ */
+export const USAGE_UNIT = Object.freeze({
+  AUDIO_SECONDS:   'audio_seconds',
+  VIDEO_SECONDS:   'video_seconds',
+  CHARACTERS:      'characters',
+  TOKENS_INPUT:    'tokens_input',
+  TOKENS_OUTPUT:   'tokens_output',
+  TOKENS_CACHED:   'tokens_cached',
+  STORAGE_BYTES:   'storage_bytes',
+  INDEX_BYTES:     'index_bytes',
+  JOB_COUNT:       'job_count',
+})
+
+export const ALL_USAGE_UNITS = Object.freeze(Object.values(USAGE_UNIT))
+
+export function isAsync(capability) {
+  return ASYNC_CAPABILITIES.includes(capability)
+}
+
+export default { CAPABILITY, ALL_CAPABILITIES, ASYNC_CAPABILITIES, QUALITY_PROFILE, ALL_QUALITY_PROFILES, SCOPE, ALL_SCOPES, USAGE_UNIT, ALL_USAGE_UNITS, isAsync }

package/src/errors.js

@@ -0,0 +1,154 @@
+/**
+ * @capsiynau/intelligence-contracts/errors
+ *
+ * The error envelope (ADR 0017). `code` is the only thing a client should
+ * branch on - codes are added, never repurposed.
+ *
+ * `message` is a neutral English DEVELOPER string. It is never end-user copy
+ * and never Welsh: products map codes to their own bilingual messages, because
+ * a platform that owns user-facing wording owns the wrong thing. `details`
+ * carries safe structured context only - never a provider name, a prompt, a
+ * stack trace or a credential.
+ */
+
+export const ERROR_CATEGORY = Object.freeze({
+  AUTH:              { prefix: 'AUTH',              status: 401 },
+  FORBIDDEN:         { prefix: 'FORBIDDEN',         status: 403 },
+  VALIDATION:        { prefix: 'VALIDATION',        status: 400 },
+  UPLOAD:            { prefix: 'UPLOAD',            status: 400 },
+  MEDIA_UNSUPPORTED: { prefix: 'MEDIA_UNSUPPORTED', status: 415 },
+  QUOTA:             { prefix: 'QUOTA',             status: 402 },
+  RATE_LIMIT:        { prefix: 'RATE_LIMIT',        status: 429 },
+  PROVIDER:          { prefix: 'PROVIDER',          status: 503 },
+  PROCESSING:        { prefix: 'PROCESSING',        status: 500 },
+  TIMEOUT:           { prefix: 'TIMEOUT',           status: 504 },
+  CONFLICT:          { prefix: 'CONFLICT',          status: 409 },
+  DUPLICATE:         { prefix: 'DUPLICATE',         status: 409 },
+  NOT_FOUND:         { prefix: 'NOT_FOUND',         status: 404 },
+  INTERNAL:          { prefix: 'INTERNAL',          status: 500 },
+})
+
+/**
+ * The published catalogue. `retryable` states whether the SAME request may be
+ * sent again - combined with an idempotency key (ADR 0013) that makes retry
+ * safe rather than merely permitted.
+ */
+export const ERROR_CODE = Object.freeze({
+  AUTH_MISSING:                   { status: 401, retryable: false, message: 'Authentication required.' },
+  AUTH_INVALID:                   { status: 401, retryable: false, message: 'The credential is not valid.' },
+  AUTH_REVOKED:                   { status: 401, retryable: false, message: 'The credential has been revoked.' },
+  FORBIDDEN_SCOPE:                { status: 403, retryable: false, message: 'The credential does not carry the required scope.' },
+  FORBIDDEN_TENANT:               { status: 403, retryable: false, message: 'The credential may not act for this tenant.' },
+  VALIDATION_FAILED:              { status: 400, retryable: false, message: 'The request failed validation.' },
+  VALIDATION_IDEMPOTENCY_KEY_REQUIRED: { status: 400, retryable: false, message: 'An Idempotency-Key header is required for this endpoint.' },
+  UPLOAD_URL_EXPIRED:             { status: 400, retryable: true,  message: 'The signed upload URL has expired.' },
+  UPLOAD_INCOMPLETE:              { status: 400, retryable: true,  message: 'The asset was not fully uploaded.' },
+  MEDIA_UNSUPPORTED_TYPE:         { status: 415, retryable: false, message: 'The media type is not supported.' },
+  MEDIA_UNSUPPORTED_DURATION:     { status: 415, retryable: false, message: 'The media exceeds the supported duration.' },
+  QUOTA_EXCEEDED:                 { status: 402, retryable: false, message: 'The tenant has exhausted its quota for this period.' },
+  RATE_LIMIT_EXCEEDED:            { status: 429, retryable: true,  message: 'Too many requests.' },
+  PROVIDER_UNAVAILABLE:           { status: 503, retryable: true,  message: 'The upstream service is temporarily unavailable.' },
+  PROVIDER_REJECTED:              { status: 502, retryable: false, message: 'The upstream service rejected the request.' },
+  PROCESSING_FAILED:              { status: 500, retryable: true,  message: 'Processing failed.' },
+  TIMEOUT_EXCEEDED:               { status: 504, retryable: true,  message: 'The operation timed out.' },
+  CONFLICT_JOB_TERMINAL:          { status: 409, retryable: false, message: 'The job has already reached a terminal state.' },
+  CONFLICT_IDEMPOTENCY_KEY_REUSE: { status: 409, retryable: false, message: 'The idempotency key was reused with a different payload.' },
+  // Added with /v1/assets. Completing an asset that is expired, failed or
+  // deleted is a conflict, not a validation error: the request is well formed
+  // and the id is real, the asset has simply moved on.
+  CONFLICT_ASSET_STATE:           { status: 409, retryable: false, message: 'The asset is not in a state that allows this.' },
+  DUPLICATE_REQUEST:              { status: 409, retryable: false, message: 'A request with this idempotency key is already in flight.' },
+  NOT_FOUND_JOB:                  { status: 404, retryable: false, message: 'No such job.' },
+  NOT_FOUND_ASSET:                { status: 404, retryable: false, message: 'No such asset.' },
+  NOT_FOUND_GLOSSARY:             { status: 404, retryable: false, message: 'No such glossary.' },
+  // Added with /v1/vocabulary. A row that belongs to ANOTHER tenant answers
+  // this too, rather than FORBIDDEN: "forbidden" would confirm the row exists,
+  // and a uuid is guessable enough that the confirmation is the leak.
+  NOT_FOUND_TERM:                 { status: 404, retryable: false, message: 'No such term.' },
+  // 7.4a: the admin credential surface addresses clients by cli_ id.
+  NOT_FOUND_CLIENT:               { status: 404, retryable: false, message: 'No such client.' },
+  // A review id and a share token both answer NOT_FOUND rather than FORBIDDEN,
+  // for the same reason a job id does: "forbidden" confirms the thing exists.
+  NOT_FOUND_REVIEW:               { status: 404, retryable: false, message: 'No such review.' },
+  // The author has finished with it. Not retryable, and not a validation
+  // problem - the request was well formed and arrived too late.
+  CONFLICT_REVIEW_FINALISED:      { status: 409, retryable: false, message: 'This review has been finalised.' },
+  // The reviewer's page is showing a version other than the one their link
+  // shared. Additive rather than reusing CONFLICT_REVIEW_FINALISED: a client
+  // should reload here, and must not offer to retry with a different version.
+  CONFLICT_REVIEW_VERSION:        { status: 409, retryable: false, message: 'This page is showing an older draft. Reload it before answering.' },
+  // Only the author closes a review. The credential proves which product is
+  // calling, not which person, so a product that serves many people sends a
+  // user reference and this is what refuses a mismatch.
+  FORBIDDEN_REVIEW_AUTHOR:        { status: 403, retryable: false, message: 'Only the author of this review can finalise it.' },
+  // Expired or revoked. One code for both: telling a holder WHICH would let
+  // them distinguish a link that never existed from one since withdrawn.
+  FORBIDDEN_REVIEW_LINK:          { status: 403, retryable: false, message: 'This review link is no longer valid.' },
+  // ── Workspace links and per-workspace credentials (Track B, B0.5) ──
+  //
+  // THESE EXISTED IN THE SERVICES BEFORE THEY EXISTED HERE, and that gap was a
+  // defect waiting for its first HTTP caller. `errorBody` resolves an unknown
+  // code to INTERNAL_ERROR, so an operator asking about a workspace nobody had
+  // linked would have received a 500 saying "an internal error occurred" -
+  // a platform fault, for a question with a correct and useful answer.
+  // src/workspaceLinks.js and src/workspaceCredentials.js are the only
+  // throwers; the list below was derived from them rather than recalled.
+  NOT_FOUND_WORKSPACE_LINK:       { status: 404, retryable: false, message: 'No link exists for that workspace.' },
+  // SEPARATE FROM FORBIDDEN_TENANT, which is about a CREDENTIAL naming a
+  // tenant it may not act for. This is about a WORKSPACE not being entitled to
+  // the tenant it claimed. Different subject, different fix, so folding them
+  // together would send an operator to the wrong half of the system.
+  FORBIDDEN_TENANT_MISMATCH:      { status: 403, retryable: false, message: 'That workspace is not entitled to act for this tenant.' },
+  // "Never consented" and "consent withdrawn" are deliberately distinct, unlike
+  // FORBIDDEN_REVIEW_LINK which merges its two cases on purpose. The reasoning
+  // inverts because the audience does: a review link is held by an outsider who
+  // must not learn which, and these are read by the operator who has to fix it.
+  FORBIDDEN_CONSENT_MISSING:      { status: 403, retryable: false, message: 'That workspace has no recorded consent.' },
+  FORBIDDEN_CONSENT_REVOKED:      { status: 403, retryable: false, message: 'Consent has been withdrawn for that workspace.' },
+  CONFLICT_WORKSPACE_LINKED:      { status: 409, retryable: false, message: 'That workspace is already linked to a different tenant.' },
+  CONFLICT_LINK_REVOKED:          { status: 409, retryable: false, message: 'Consent was withdrawn for that workspace; re-granting it is a deliberate act.' },
+  CONFLICT_CREDENTIAL_EXISTS:     { status: 409, retryable: false, message: 'That workspace already holds a credential; rotate it rather than issuing a second.' },
+  CONFLICT_CREDENTIAL_ATTACHED:   { status: 409, retryable: false, message: 'That workspace still holds a credential; withdraw it so the credential is revoked with the consent.' },
+  // NOT retryable, and that is the whole point of it having its own code. The
+  // credential was minted and could not be attached to its link, so a retry
+  // would mint a second. The message carries what to do instead.
+  CONFLICT_LINK_NOT_UPDATED:      { status: 409, retryable: false, message: 'A credential was issued but could not be attached to its workspace link.' },
+  METHOD_NOT_ALLOWED:             { status: 405, retryable: false, message: 'That method is not allowed on this route.' },
+  SERVICE_UNAVAILABLE:            { status: 503, retryable: true,  message: 'The platform is not accepting requests.' },
+  INTERNAL_ERROR:                 { status: 500, retryable: true,  message: 'An internal error occurred.' },
+})
+
+export const ALL_ERROR_CODES = Object.freeze(Object.keys(ERROR_CODE))
+
+/**
+ * Build the wire envelope.
+ *
+ * @param {string} code       a key of ERROR_CODE
+ * @param {object} [opts]
+ * @param {string} [opts.requestId]
+ * @param {object} [opts.details]  safe structured context only
+ * @param {string} [opts.message]  override the developer string
+ */
+export function errorBody(code, { requestId = null, details = {}, message } = {}) {
+  const spec = ERROR_CODE[code] || ERROR_CODE.INTERNAL_ERROR
+  const resolved = ERROR_CODE[code] ? code : 'INTERNAL_ERROR'
+  return {
+    error: {
+      code: resolved,
+      message: message || spec.message,
+      requestId,
+      retryable: spec.retryable,
+      details,
+    },
+  }
+}
+
+export function statusFor(code) {
+  return (ERROR_CODE[code] || ERROR_CODE.INTERNAL_ERROR).status
+}
+
+export function isRetryable(code) {
+  return (ERROR_CODE[code] || ERROR_CODE.INTERNAL_ERROR).retryable
+}
+
+export default { ERROR_CATEGORY, ERROR_CODE, ALL_ERROR_CODES, errorBody, statusFor, isRetryable }

package/src/events.js

@@ -0,0 +1,114 @@
+/**
+ * @capsiynau/intelligence-contracts/events
+ *
+ * Events, delivered by webhook or observed by polling (ADR 0018).
+ *
+ * TWO FAMILIES, one envelope. A job event names a job, a capability and a
+ * status; a review event names a review and nothing else - a review is not a
+ * job, nothing runs, and there is no status to report. `validateEvent`
+ * discriminates on the type's own prefix rather than demanding job fields of
+ * everything.
+ *
+ * Delivery is AT-LEAST-ONCE. Consumers must be idempotent on `event_id` -
+ * a redelivery is normal operation, not an error, and a consumer that acts
+ * twice on one event has a bug the platform cannot fix for it.
+ */
+
+export const EVENT_TYPE = Object.freeze({
+  JOB_QUEUED:              'job.queued',
+  JOB_PROCESSING:          'job.processing',
+  JOB_PROGRESS:            'job.progress',
+  JOB_COMPLETED:           'job.completed',
+  JOB_PARTIALLY_COMPLETED: 'job.partially_completed',
+  JOB_FAILED:              'job.failed',
+  JOB_CANCELLED:           'job.cancelled',
+
+  // Review history. Append-only and human-scale: these are the lines an author
+  // reads as a timeline, and the same rows a future knowledge layer may read
+  // (never write) to learn who reviews what.
+  REVIEW_CREATED:       'review.created',
+  REVIEW_VERSION_ADDED: 'review.version_added',
+  REVIEW_SHARED:        'review.shared',
+  REVIEW_OPENED:        'review.opened',
+  REVIEW_COMMENTED:     'review.commented',
+  REVIEW_SUGGESTED:     'review.suggested',
+  REVIEW_DECIDED:       'review.decided',
+  REVIEW_FINALISED:     'review.finalised',
+  REVIEW_LINK_REVOKED:  'review.link_revoked',
+})
+
+export const ALL_EVENT_TYPES = Object.freeze(Object.values(EVENT_TYPE))
+
+/** Signature header, and the window inside which a signed body is accepted. */
+export const SIGNATURE_HEADER = 'X-Signature'
+export const REQUEST_ID_HEADER = 'X-Request-Id'
+export const IDEMPOTENT_REPLAY_HEADER = 'X-Idempotent-Replay'
+export const IDEMPOTENCY_KEY_HEADER = 'Idempotency-Key'
+export const TENANT_HEADER = 'X-Tenant-Reference'
+export const USER_HEADER = 'X-User-Reference'
+
+/** Replay window in seconds. A timestamp outside it must be rejected. */
+export const SIGNATURE_TOLERANCE_SECONDS = 300
+
+/**
+ * Keys present on every event envelope, whatever it is about.
+ *
+ * `job_id`, `capability` and `status` are NOT here (Codex, #1637). They belong
+ * to a job, and a review is not a job: it has no capability, nothing runs, and
+ * there is no status to report. Requiring them of every event meant a review
+ * event either failed validation or carried invented job fields - and the
+ * review types were already in EVENT_TYPE, so this validator rejected events
+ * the contract itself publishes.
+ */
+export const REQUIRED_EVENT_KEYS = Object.freeze(['event_id', 'type', 'occurred_at'])
+
+/** What a JOB event carries beyond the common keys. */
+export const REQUIRED_JOB_EVENT_KEYS = Object.freeze(['job_id', 'capability', 'status'])
+
+/** What a REVIEW event carries beyond the common keys. */
+export const REQUIRED_REVIEW_EVENT_KEYS = Object.freeze(['review_id'])
+
+/**
+ * The family an event type belongs to, from its own name.
+ *
+ * Additive by construction: a new family is a new prefix and a new key list,
+ * and an unknown prefix validates against the common keys alone rather than
+ * being rejected for missing fields its family never had.
+ */
+export function eventFamily(type) {
+  if (typeof type !== 'string') return null
+  const [family] = type.split('.')
+  return family || null
+}
+
+const FAMILY_KEYS = Object.freeze({
+  job: REQUIRED_JOB_EVENT_KEYS,
+  review: REQUIRED_REVIEW_EVENT_KEYS,
+})
+
+export function validateEvent(event) {
+  const problems = []
+  if (!event || typeof event !== 'object') return { valid: false, problems: ['event is not an object'] }
+
+  const required = [...REQUIRED_EVENT_KEYS, ...(FAMILY_KEYS[eventFamily(event.type)] || [])]
+  for (const key of required) {
+    if (event[key] === undefined || event[key] === null) problems.push(`missing ${key}`)
+  }
+  if (event.type && !ALL_EVENT_TYPES.includes(event.type)) problems.push(`unknown type ${event.type}`)
+  return { valid: problems.length === 0, problems }
+}
+
+export default {
+  EVENT_TYPE,
+  ALL_EVENT_TYPES,
+  eventFamily,
+  SIGNATURE_HEADER,
+  REQUEST_ID_HEADER,
+  IDEMPOTENT_REPLAY_HEADER,
+  IDEMPOTENCY_KEY_HEADER,
+  TENANT_HEADER,
+  USER_HEADER,
+  SIGNATURE_TOLERANCE_SECONDS,
+  REQUIRED_EVENT_KEYS,
+  validateEvent,
+}

package/src/index.js

@@ -0,0 +1,20 @@
+/**
+ * @capsiynau/intelligence-contracts
+ *
+ * The wire contract between products and the Intelligence Layer: job statuses,
+ * error codes, capability and scope names, the segment model, event schemas.
+ *
+ * WHAT MUST NEVER LAND HERE (ADR 0006, ADR 0010): provider implementations,
+ * prompts, model names, routing or fallback logic, quality-profile internals,
+ * or anything else from which the platform could be reconstructed. The reading
+ * test is simple - a developer holding only this package and the client should
+ * be unable to rebuild the implementation. If a type encodes HOW something is
+ * computed rather than WHAT is exchanged, it belongs in the platform.
+ *
+ * Private by design: `"private": true` in package.json. This is not published.
+ */
+export * from './jobs.js'
+export * from './errors.js'
+export * from './capabilities.js'
+export * from './segments.js'
+export * from './events.js'

package/src/jobs.js

@@ -0,0 +1,83 @@
+/**
+ * @capsiynau/intelligence-contracts/jobs
+ *
+ * One job lifecycle for every asynchronous capability (ADR 0018). Products
+ * poll or subscribe against these statuses; the platform is free to change
+ * how work is done, never what a status means.
+ */
+
+/** Every status a job may hold. */
+export const JOB_STATUS = Object.freeze({
+  QUEUED:               'queued',
+  VALIDATING:           'validating',
+  PROCESSING:           'processing',
+  COMPLETED:            'completed',
+  PARTIALLY_COMPLETED:  'partially_completed',
+  FAILED:               'failed',
+  CANCEL_REQUESTED:     'cancel_requested',
+  CANCELLED:            'cancelled',
+  EXPIRED:              'expired',
+})
+
+export const ALL_STATUSES = Object.freeze(Object.values(JOB_STATUS))
+
+/**
+ * Statuses from which a job will never move again.
+ *
+ * `partially_completed` is terminal on purpose: a 90-minute programme whose
+ * last two minutes failed is worth returning, and forcing it to `failed`
+ * throws away work the client has already paid for.
+ */
+export const TERMINAL_STATUSES = Object.freeze([
+  JOB_STATUS.COMPLETED,
+  JOB_STATUS.PARTIALLY_COMPLETED,
+  JOB_STATUS.FAILED,
+  JOB_STATUS.CANCELLED,
+  JOB_STATUS.EXPIRED,
+])
+
+/** Statuses whose result is readable. */
+export const RESULT_BEARING_STATUSES = Object.freeze([
+  JOB_STATUS.COMPLETED,
+  JOB_STATUS.PARTIALLY_COMPLETED,
+])
+
+/**
+ * Legal transitions. The platform enforces these; the contract publishes them
+ * so a client can reason about what it will see next without guessing.
+ */
+export const TRANSITIONS = Object.freeze({
+  [JOB_STATUS.QUEUED]:              [JOB_STATUS.VALIDATING, JOB_STATUS.PROCESSING, JOB_STATUS.CANCEL_REQUESTED, JOB_STATUS.CANCELLED, JOB_STATUS.FAILED],
+  [JOB_STATUS.VALIDATING]:          [JOB_STATUS.PROCESSING, JOB_STATUS.FAILED, JOB_STATUS.CANCEL_REQUESTED],
+  [JOB_STATUS.PROCESSING]:          [JOB_STATUS.COMPLETED, JOB_STATUS.PARTIALLY_COMPLETED, JOB_STATUS.FAILED, JOB_STATUS.CANCEL_REQUESTED],
+  [JOB_STATUS.CANCEL_REQUESTED]:    [JOB_STATUS.CANCELLED, JOB_STATUS.COMPLETED, JOB_STATUS.PARTIALLY_COMPLETED, JOB_STATUS.FAILED],
+  [JOB_STATUS.COMPLETED]:           [JOB_STATUS.EXPIRED],
+  [JOB_STATUS.PARTIALLY_COMPLETED]: [JOB_STATUS.EXPIRED],
+  [JOB_STATUS.FAILED]:              [JOB_STATUS.EXPIRED],
+  [JOB_STATUS.CANCELLED]:           [],
+  [JOB_STATUS.EXPIRED]:             [],
+})
+
+export function isTerminal(status) {
+  return TERMINAL_STATUSES.includes(status)
+}
+
+export function hasResult(status) {
+  return RESULT_BEARING_STATUSES.includes(status)
+}
+
+/**
+ * `cancel_requested` may still end in `completed`: cancellation is cooperative
+ * and best-effort (ADR 0016), so a job already inside a provider call can
+ * finish before the worker reaches its next checkpoint.
+ */
+export function canTransition(from, to) {
+  return (TRANSITIONS[from] || []).includes(to)
+}
+
+/** Statuses a client should keep polling. */
+export function isPending(status) {
+  return !isTerminal(status)
+}
+
+export default { JOB_STATUS, ALL_STATUSES, TERMINAL_STATUSES, RESULT_BEARING_STATUSES, TRANSITIONS, isTerminal, hasResult, canTransition, isPending }

package/src/segments.js

@@ -0,0 +1,141 @@
+/**
+ * @capsiynau/intelligence-contracts/segments
+ *
+ * The caption segment as it crosses the wire, and the invariants that must
+ * survive a round trip through translation (ADR 0017, target architecture §3.3).
+ *
+ * This file describes the SHAPE only. Segmentation, line breaking and timing
+ * correction are platform implementation and live nowhere near here - a
+ * developer holding the contracts package must not be able to reconstruct how
+ * a segment is produced, only what one looks like (ADR 0006).
+ */
+
+/** Required keys on every segment crossing the boundary. */
+export const REQUIRED_SEGMENT_KEYS = Object.freeze(['segment_id', 'start', 'end', 'text'])
+
+/** Optional keys the platform may return and a client may send back. */
+export const OPTIONAL_SEGMENT_KEYS = Object.freeze([
+  'speaker', 'language', 'confidence', 'line_breaks', 'source_text', 'formatting',
+])
+
+/**
+ * Keys translation must preserve byte-for-byte. Only `text` may change.
+ *
+ * A translation that renumbers, drops or re-times a segment is a CONTRACT
+ * VIOLATION, not a quality problem - the caller's editor state, styling and
+ * corrections are all keyed on `segment_id`, so losing it silently destroys
+ * work that looks intact until someone opens the file.
+ */
+export const TRANSLATION_INVARIANT_KEYS = Object.freeze([
+  'segment_id', 'start', 'end', 'speaker', 'line_breaks', 'formatting',
+])
+
+/**
+ * Has the text in these segments already been through a corrector?
+ *
+ * A property of the SEGMENTS a client sends, not of how the client made them.
+ * The platform needs it because some outputs QUOTE the caller's text back -
+ * `moments[].quote` is "the exact text of the moment" - and a quote may only be
+ * corrected when the transcript it was taken from was corrected. Correct a
+ * quote taken from raw text and it stops appearing in the transcript it claims
+ * to come from, while reading as better language than the transcript does.
+ *
+ * ABSENT MEANS TRUE. Corrected transcripts are the normal case and were the
+ * only case before this field existed, so an older client keeps its behaviour.
+ * A client sending raw provider text sends false explicitly.
+ *
+ * WHY NOT THE CLIENT'S OWN NAME FOR IT (ADR 0003, ADR 0006). Capsiynau reaches
+ * this state through a `verbatim` caption style, and passing that style through
+ * would put a product's caption vocabulary into the wire contract and let a
+ * reader of this package infer how the platform cuts captions. It does not cut
+ * them. One boolean about the input says everything the platform is entitled
+ * to know.
+ */
+export const TRANSCRIPT_NORMALISED_KEY = 'transcript_normalised'
+
+/** Absent means the transcript was corrected. Only an explicit false is raw. */
+export function isTranscriptNormalised(request) {
+  return request?.[TRANSCRIPT_NORMALISED_KEY] !== false
+}
+
+export const TIMESTAMP_GRANULARITY = Object.freeze({ SEGMENT: 'segment', WORD: 'word' })
+
+export const DIARISATION = Object.freeze({ OFF: 'off', AUTO: 'auto' })
+
+/** `speakers:<n>` where n is a positive integer, or one of DIARISATION. */
+export function isValidDiarisation(value) {
+  if (Object.values(DIARISATION).includes(value)) return true
+  const m = /^speakers:(\d+)$/.exec(String(value ?? ''))
+  return Boolean(m) && Number(m[1]) > 0
+}
+
+/**
+ * Structural check on one segment. Deliberately shallow: this validates the
+ * contract, not the content. It answers "could a client consume this", never
+ * "is this a good caption".
+ *
+ * @returns {{ valid: boolean, problems: string[] }}
+ */
+export function validateSegment(segment) {
+  const problems = []
+  if (!segment || typeof segment !== 'object') return { valid: false, problems: ['segment is not an object'] }
+
+  for (const key of REQUIRED_SEGMENT_KEYS) {
+    if (segment[key] === undefined || segment[key] === null) problems.push(`missing ${key}`)
+  }
+  if (segment.start !== undefined && typeof segment.start !== 'number') problems.push('start must be a number')
+  if (segment.end !== undefined && typeof segment.end !== 'number') problems.push('end must be a number')
+  if (typeof segment.start === 'number' && typeof segment.end === 'number' && segment.end < segment.start) {
+    problems.push('end precedes start')
+  }
+  if (segment.text !== undefined && typeof segment.text !== 'string') problems.push('text must be a string')
+
+  return { valid: problems.length === 0, problems }
+}
+
+/**
+ * Prove a translation preserved everything except `text`.
+ *
+ * Used by contract tests on both sides of the boundary: the platform asserts
+ * it before returning, a product may assert it on receipt.
+ *
+ * @returns {{ valid: boolean, problems: string[] }}
+ */
+export function validateTranslationRoundTrip(source, translated) {
+  const problems = []
+  if (!Array.isArray(source) || !Array.isArray(translated)) {
+    return { valid: false, problems: ['both sides must be arrays'] }
+  }
+  if (source.length !== translated.length) {
+    problems.push(`segment count changed: ${source.length} -> ${translated.length}`)
+  }
+
+  const byId = new Map(translated.map((s) => [s?.segment_id, s]))
+  for (const src of source) {
+    const out = byId.get(src?.segment_id)
+    if (!out) {
+      problems.push(`segment ${src?.segment_id} missing from the translation`)
+      continue
+    }
+    for (const key of TRANSLATION_INVARIANT_KEYS) {
+      if (src[key] === undefined && out[key] === undefined) continue
+      if (JSON.stringify(src[key]) !== JSON.stringify(out[key])) {
+        problems.push(`segment ${src.segment_id}: ${key} changed`)
+      }
+    }
+  }
+  return { valid: problems.length === 0, problems }
+}
+
+export default {
+  TRANSCRIPT_NORMALISED_KEY,
+  isTranscriptNormalised,
+  REQUIRED_SEGMENT_KEYS,
+  OPTIONAL_SEGMENT_KEYS,
+  TRANSLATION_INVARIANT_KEYS,
+  TIMESTAMP_GRANULARITY,
+  DIARISATION,
+  isValidDiarisation,
+  validateSegment,
+  validateTranslationRoundTrip,
+}

package/types/index.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Typed surface of the wire contract. Shapes only - nothing here reveals how
+ * the platform produces a result (ADR 0006).
+ */
+
+export type JobStatus =
+  | 'queued' | 'validating' | 'processing'
+  | 'completed' | 'partially_completed' | 'failed'
+  | 'cancel_requested' | 'cancelled' | 'expired'
+
+export type Capability =
+  | 'transcription' | 'translation' | 'language' | 'captions'
+  | 'glossary' | 'analysis' | 'search' | 'media' | 'live'
+
+export type QualityProfile = 'fast' | 'accurate' | 'welsh-broadcast'
+
+export type UsageUnit =
+  | 'audio_seconds' | 'video_seconds' | 'characters'
+  | 'tokens_input' | 'tokens_output' | 'tokens_cached'
+  | 'storage_bytes' | 'index_bytes' | 'job_count'
+
+export interface Segment {
+  segment_id: string
+  start: number
+  end: number
+  text: string
+  speaker?: string
+  language?: string
+  confidence?: number
+  line_breaks?: number[]
+  source_text?: string
+  formatting?: Record<string, unknown>
+}
+
+export interface JobProgress {
+  stage: string
+  /** Present only where the number is real - never fabricated. */
+  percent?: number
+}
+
+export interface Job {
+  job_id: string
+  status: JobStatus
+  capability: Capability
+  progress?: JobProgress
+  created_at: string
+  updated_at: string
+  client_reference?: string | null
+  result: { available: boolean; url?: string }
+  error: ErrorEnvelope['error'] | null
+  usage?: Partial<Record<UsageUnit, number>>
+  processing?: { attempts: number; queue_seconds: number; quality_profile: QualityProfile }
+}
+
+export interface ErrorEnvelope {
+  error: {
+    code: string
+    /** Neutral English developer string. Never end-user copy, never Welsh. */
+    message: string
+    requestId: string | null
+    retryable: boolean
+    details: Record<string, unknown>
+  }
+}
+
+export interface JobEvent {
+  event_id: string
+  type: 'job.queued' | 'job.processing' | 'job.progress' | 'job.completed'
+      | 'job.partially_completed' | 'job.failed' | 'job.cancelled'
+  job_id: string
+  capability: Capability
+  status: JobStatus
+  occurred_at: string
+  client_reference?: string | null
+}
+
+export interface ValidationResult { valid: boolean; problems: string[] }
+
+export declare function isTerminal(status: JobStatus): boolean
+export declare function hasResult(status: JobStatus): boolean
+export declare function isPending(status: JobStatus): boolean
+export declare function canTransition(from: JobStatus, to: JobStatus): boolean
+export declare function errorBody(code: string, opts?: { requestId?: string | null; details?: Record<string, unknown>; message?: string }): ErrorEnvelope
+export declare function statusFor(code: string): number
+export declare function isRetryable(code: string): boolean
+export declare function isAsync(capability: Capability): boolean
+export declare function isValidDiarisation(value: string): boolean
+export declare function validateSegment(segment: unknown): ValidationResult
+export declare function validateTranslationRoundTrip(source: Segment[], translated: Segment[]): ValidationResult
+export declare const REQUIRED_EVENT_KEYS: readonly string[]
+export declare const REQUIRED_JOB_EVENT_KEYS: readonly string[]
+export declare const REQUIRED_REVIEW_EVENT_KEYS: readonly string[]
+/** The family an event type belongs to ("job", "review"), from its own prefix. */
+export declare function eventFamily(type: unknown): string | null
+export declare function validateEvent(event: unknown): ValidationResult