Files
0pt/src/platform/siax-context.ts
T
Simon AxelssonandClaude Fable 5 b7038d7675 feat(platform): canonical SIAX context/errors + real-contract clients, no prod mock fallback
- src/platform/: SiaxRequestContext + propagation headers + 12 canonical
  error codes (documented mirror of cl0ud packages/contract), SiaxError,
  resource refs (st0re:artifact:...), and the §3/§10 dependency-mode guard:
  production runtime + unconfigured dependency/store => hard
  DEPENDENCY_UNAVAILABLE at construction, never silent mock/in-memory.
- src/clients/: all four platform clients rewritten against the REAL wire
  contracts verified on sibling main branches this session:
  * cl0ud: POST /api/policy/evaluate ({data} envelope, allow+requiresApproval)
    - the old /v1/cl0ud/policies/evaluate path never existed on CL0UD
  * st0re: camelCase ArtifactInput on /v1/st0re/artifacts/register incl.
    X-Tenant-Id/X-Actor-Id + X-Idempotency-Key - the old snake_case body
    would have been a 400 against the live registry
  * n0d: required_role + resource_requirements + body idempotency_key +
    CloudEvents callback_url per n0d createJobSchema; adds getJob/getJobResult
  * aud0: /v1/aud0/openlineage is AUD0's only lineage ingest -
    /v1/aud0/lineage/events never existed; legacy shape converts to a
    spec-shaped OpenLineage RunEvent (deterministic runId dedup)
- src/lineage/: OpenLineage subset types + LineageEmitter (never-throw,
  §16 evidence semantics)
- shared SiaxHttp transport: timeouts, typed SiaxError mapping, context
  propagation, no raw upstream bodies in errors

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-08-31 16:35:01 +02:00

105 lines
4.5 KiB
TypeScript

/**
* src/platform/siax-context.ts
* =============================
* MIRROR of cl0ud's canonical cross-product request context
* (`sax3l/cl0ud` `packages/contract/src/request-context.ts`, merged to cl0ud
* main 2026-08-31). Mirrored — NOT imported — because `@siax/contract` is not
* published to a registry this repo consumes yet; the mirror posture is the
* same one cl0ud itself documents for its platform-core `ErrorCode` mirror
* ("KEEP ALIGNED; drift is a review catch and a test failure").
* tests/contracts/siax-context.contract.test.ts pins every header name and
* field so drift against the canonical source fails loudly here.
*
* TRUST BOUNDARY (verbatim from the canonical source): this context is a
* CARRIER, not a VERIFIER. A receiving service derives its tenant from the
* VERIFIED caller; the `x-tenant-id` propagation header is honoured only for
* a verified machine/service principal. The cryptographic binding is the
* service credential on the Authorization header — this context rides
* alongside it for scoping, policy and tracing.
*/
/** The canonical SIAX cross-product request context (Master-DoD §4). */
export interface SiaxRequestContext {
/** The tenant this call acts for (`t_<slug>` spine). Server-derived. */
tenantId: string;
/** The bound project within the tenant, when the operation is project-scoped. */
projectId?: string;
/** The acting subject: a user `sub`, or a service/machine identity id. */
actorId: string;
/** The capability being invoked — canonical dotted registry id, e.g. `0pt.search.query.v1`. */
capability: string;
/** Optional GDPR/purpose-limitation tag, e.g. `valuation`, `support`, `billing`. */
purpose?: string;
/** Correlation id shared by every hop of one logical operation. */
correlationId: string;
/** The id of the event/request that CAUSED this one (event-chain lineage). */
causationId?: string;
/** Distributed-tracing trace id (W3C trace-context compatible where possible). */
traceId?: string;
/** Idempotency key for retried writes — same key ⇒ same effect, exactly once. */
idempotencyKey?: string;
}
/**
* Canonical wire headers for propagating a {@link SiaxRequestContext} on
* service-to-service calls. Names are pinned to cl0ud's
* `SIAX_CONTEXT_HEADERS` verbatim.
*/
export const SIAX_CONTEXT_HEADERS = {
tenant: "x-tenant-id",
actor: "x-actor-id",
capability: "x-siax-capability",
purpose: "x-siax-purpose",
project: "x-siax-project-id",
correlation: "x-siax-correlation-id",
causation: "x-siax-causation-id",
trace: "x-siax-trace-id",
idempotency: "idempotency-key",
} as const;
/**
* Serialize a context to the canonical propagation headers for an OUTBOUND
* service-to-service call. The caller adds its own service `Authorization` —
* this function deliberately has no way to carry a token.
*/
export function toPropagationHeaders(ctx: SiaxRequestContext): Record<string, string> {
const h: Record<string, string> = {
[SIAX_CONTEXT_HEADERS.tenant]: ctx.tenantId,
[SIAX_CONTEXT_HEADERS.actor]: ctx.actorId,
[SIAX_CONTEXT_HEADERS.capability]: ctx.capability,
[SIAX_CONTEXT_HEADERS.correlation]: ctx.correlationId,
};
if (ctx.projectId) h[SIAX_CONTEXT_HEADERS.project] = ctx.projectId;
if (ctx.purpose) h[SIAX_CONTEXT_HEADERS.purpose] = ctx.purpose;
if (ctx.causationId) h[SIAX_CONTEXT_HEADERS.causation] = ctx.causationId;
if (ctx.traceId) h[SIAX_CONTEXT_HEADERS.trace] = ctx.traceId;
if (ctx.idempotencyKey) h[SIAX_CONTEXT_HEADERS.idempotency] = ctx.idempotencyKey;
return h;
}
/**
* Pure structural validation of a candidate context (e.g. before persisting
* to an audit/lineage record). Returns a list of problems — empty means
* valid. NOT an authorization check.
*/
export function validateSiaxRequestContext(ctx: Partial<SiaxRequestContext>): string[] {
const problems: string[] = [];
const requireNonEmpty = (field: keyof SiaxRequestContext) => {
const v = ctx[field];
if (typeof v !== "string" || v.trim().length === 0) {
problems.push(`${field} is required and must be a non-empty string`);
}
};
requireNonEmpty("tenantId");
requireNonEmpty("actorId");
requireNonEmpty("capability");
requireNonEmpty("correlationId");
for (const field of ["projectId", "purpose", "causationId", "traceId", "idempotencyKey"] as const) {
const v = ctx[field];
if (v !== undefined && (typeof v !== "string" || v.trim().length === 0)) {
problems.push(`${field}, when present, must be a non-empty string`);
}
}
return problems;
}