diff --git a/src/clients/aud0-client.ts b/src/clients/aud0-client.ts index b9fdda3..60e510f 100644 --- a/src/clients/aud0-client.ts +++ b/src/clients/aud0-client.ts @@ -2,28 +2,43 @@ * src/clients/aud0-client.ts * =========================== * 0pt's ONLY path for recording "what happened" to AUD0, the SIAX Cloud - * append-only system of record. Every mutating capability in this repo emits - * a plain event (`ingestEvent`) and, where the mutation produced or - * transformed something, a lineage edge (`ingestLineageEvent`) -- see - * docs/ICEBERG_WRITE_BOUNDARY.md's "Event names" table for the full list this - * client backs. Two endpoints: - * - ingestEvent -> POST {baseUrl}/v1/aud0/events - * - ingestLineageEvent -> POST {baseUrl}/v1/aud0/lineage/events + * append-only system of record. * - * Convention (identical to cl0ud-client.ts / n0d-client.ts / st0re-client.ts - * / st0re-lakehouse-client.ts): when no base URL is configured the client is - * a NO-OP -- it does not attempt any network call, it never throws, and it - * never blocks a caller. AUD0 is a best-effort, out-of-band audit sink for - * 0pt; a missing AUD0_URL (unit tests, local dev) must not turn every - * capability call into a failed fetch to `undefined`. That matches AUD0's own - * documented stance that an audit emission is a record of what already - * happened, not a gate the action waits on. + * REWRITTEN 2026-08-31 against AUD0's REAL wire contract (sax3l/aud0 branch + * feat/siax-platforms-p0-evidence-os, `src/api/routes.ts` + + * `src/schemas/event.ts` + `src/api/routes/openlineage.ts`, verified this + * session): * - * HONESTY NOTE: no AUD0_URL has been available to probe in any pass so far -- - * AUD0 has no live ingestion endpoint wired for 0pt yet. A real deployment - * must be pointed at via `aud0BaseUrl`/`AUD0_URL` before events emitted - * through this client are durable anywhere. + * ingestEvent -> POST {baseUrl}/v1/aud0/events (snake_case) + * ingestOpenLineageEvent-> POST {baseUrl}/v1/aud0/openlineage?tenant_id=&app_id= + * ingestLineageEvent -> LEGACY SHIM: converts the historical 0pt lineage + * shape to an OpenLineage RunEvent and posts it to + * the endpoint above. + * + * The path this client used to post lineage to — `/v1/aud0/lineage/events` — + * DOES NOT EXIST on AUD0 and never has. AUD0's only lineage ingest is the + * OpenLineage endpoint; `/v1/aud0/lineage/*` routes are read-only projections + * of the generic event stream. Master-DoD §16 requires OpenLineage run/job/ + * dataset ingest — the emitter in src/lineage/ produces spec-shaped + * RunEvents; this client is just the wire. + * + * The audit-event contract additionally carries the P0 evidence-context + * fields (§16: purpose, policy decision, correlation, causation, trace, + * result, references), all optional on the wire; they are surfaced on + * `Aud0Event` so services can populate them. + * + * Production fallback policy (Master-DoD §3/§10): no base URL in a + * production runtime throws `SiaxError("DEPENDENCY_UNAVAILABLE")` at + * construction. The no-op client survives only for non-production runtimes. + * NOTE the deliberate asymmetry: audit emission FAILURE at runtime (AUD0 + * down) still does not roll back the already-performed action — an audit + * emission records what already happened; the durability requirement is + * §70's "durable local/outbox path", tracked honestly in STATUS.md as a gap. */ +import { SiaxHttp } from "./http"; +import { resolveDependencyBaseUrl } from "../platform/dependency-mode"; +import type { SiaxRequestContext } from "../platform/siax-context"; +import type { OpenLineageRunEvent } from "../lineage/openlineage"; export interface Aud0Event { event_id: string; @@ -37,16 +52,28 @@ export interface Aud0Event { resource_id: string; /** Risk level L0–L5 per the SIAX Cloud risk taxonomy. */ risk_level: string; - /** - * Free-form event body. Optional and `unknown`-typed so every call site in - * this repo type-checks: most emit a structured `Record`, - * some emit nothing at all. - */ payload?: unknown; created_at: string; correlation_id?: string; + // P0 evidence-context fields (Master-DoD §16), optional on AUD0's wire. + /** Business time, when it differs from ingestion time. */ + occurred_at?: string; + /** GDPR/purpose-limitation tag. */ + purpose?: string; + /** CL0UD policy decision id/reason for the action being recorded. */ + policy_decision?: string; + causation_id?: string; + trace_id?: string; + /** Outcome, e.g. "success" | "failure". */ + result?: string; + /** Canonical resource refs consumed by the action (e.g. st0re:artifact:...). */ + input_refs?: string[]; + /** Canonical resource refs produced by the action. */ + output_refs?: string[]; + idempotency_key?: string; } +/** Historical 0pt lineage shape — kept as the input to the legacy shim. */ export interface Aud0LineageEvent { lineage_event_id: string; tenant_id: string; @@ -69,58 +96,135 @@ export type Aud0EventInput = Aud0Event; /** Alias so both historical import names resolve to the same shape. */ export type Aud0LineageEventInput = Aud0LineageEvent; -export interface Aud0Client { - ingestEvent(event: Aud0Event): Promise; - ingestLineageEvent(event: Aud0LineageEvent): Promise; +/** AUD0's OpenLineage ingest acknowledgement. */ +export interface Aud0OpenLineageAck { + tenant_id: string; + run_id: string; + job: string; + event_id: string; + evidence_id?: string; + deduplicated?: boolean; } -export function createAud0Client(baseUrl?: string): Aud0Client { - if (!baseUrl) return new NoopAud0Client(); - return new HttpAud0Client(baseUrl); +export interface Aud0Client { + ingestEvent(event: Aud0Event, context?: SiaxRequestContext): Promise; + ingestOpenLineageEvent( + tenantId: string, + appId: string, + event: OpenLineageRunEvent, + context?: SiaxRequestContext + ): Promise; + /** @deprecated Legacy shim — converts to OpenLineage and posts to /v1/aud0/openlineage. */ + ingestLineageEvent(event: Aud0LineageEvent, context?: SiaxRequestContext): Promise; +} + +export function createAud0Client(baseUrl?: string, opts?: { token?: string }): Aud0Client { + const resolved = resolveDependencyBaseUrl("aud0", baseUrl ?? process.env.AUD0_URL); + if (!resolved) return new NoopAud0Client(); + return new HttpAud0Client(resolved, opts?.token ?? process.env.AUD0_SERVICE_TOKEN); } /** - * No AUD0_URL configured: audit emission is a no-op (see module doc comment). - * Echoes the event back so callers that want the emitted record get the same - * value shape they would from the HTTP client. + * Convert the historical 0pt lineage shape into a spec-shaped OpenLineage + * RunEvent (AUD0's only lineage ingest contract). Deterministic: the runId is + * the legacy lineage_event_id, so idempotent re-emission dedups on AUD0's + * `ol:::` key. */ +export function legacyLineageToOpenLineage(event: Aud0LineageEvent): OpenLineageRunEvent { + return { + eventType: "COMPLETE", + eventTime: event.created_at, + producer: "https://git.siax.io/sax3l/0pt", + run: { + runId: event.lineage_event_id, + facets: { + ...(event.correlation_id + ? { siaxCorrelation: { correlation_id: event.correlation_id } } + : {}), + siaxLegacyLineage: { + lineage_type: event.lineage_type, + capability_id: event.capability_id, + project_id: event.project_id, + ...(event.metadata !== undefined ? { metadata: event.metadata } : {}), + }, + }, + }, + job: { namespace: event.app_id, name: event.capability_id }, + inputs: [{ namespace: event.app_id, name: `${event.source_type}/${event.source_id}` }], + outputs: [{ namespace: event.app_id, name: `${event.target_type}/${event.target_id}` }], + }; +} + +/** Non-production runtimes only: audit emission is a no-op echo. */ class NoopAud0Client implements Aud0Client { async ingestEvent(event: Aud0Event): Promise { return event; } + async ingestOpenLineageEvent( + tenantId: string, + _appId: string, + event: OpenLineageRunEvent + ): Promise { + return { + tenant_id: tenantId, + run_id: event.run.runId, + job: `${event.job.namespace}/${event.job.name}`, + event_id: `noop_${event.run.runId}`, + }; + } async ingestLineageEvent(event: Aud0LineageEvent): Promise { return event; } } class HttpAud0Client implements Aud0Client { - private readonly baseUrl: string; + private readonly http: SiaxHttp; - constructor(baseUrl: string) { - // Normalize so `${baseUrl}/v1/...` never produces a double slash. - this.baseUrl = baseUrl.replace(/\/+$/, ""); + constructor(baseUrl: string, token?: string) { + this.http = new SiaxHttp({ dependency: "aud0", baseUrl, token }); } - async ingestEvent(event: Aud0Event): Promise { - return this.post("/v1/aud0/events", event); - } - - async ingestLineageEvent(event: Aud0LineageEvent): Promise { - return this.post("/v1/aud0/lineage/events", event); - } - - private async post(path: string, body: T): Promise { - const res = await fetch(`${this.baseUrl}${path}`, { + async ingestEvent(event: Aud0Event, context?: SiaxRequestContext): Promise { + const res = await this.http.request({ method: "POST", - headers: { "Content-Type": "application/json" }, - body: JSON.stringify(body), + path: "/v1/aud0/events", + context, + headers: { "X-Tenant-Id": event.tenant_id, "X-Actor-Id": event.actor_id }, + body: event, + // 200 = idempotent replay (deduplicated: true) — a success. + acceptStatuses: [200], }); - if (!res.ok) { - throw new Error(`AUD0 ${path} error: ${res.status} ${await res.text().catch(() => "")}`); - } - // AUD0 is not guaranteed to echo a JSON body on ingest. Prefer the - // server's canonical record when there is one, otherwise fall back to what - // we sent -- never fail an already-successful POST on an empty body. - return (await res.json().catch(() => body)) as T; + // Prefer AUD0's canonical stored record; fall back to what we sent. + return (res.json ?? event) as Aud0Event; + } + + async ingestOpenLineageEvent( + tenantId: string, + appId: string, + event: OpenLineageRunEvent, + context?: SiaxRequestContext + ): Promise { + const res = await this.http.request({ + method: "POST", + path: "/v1/aud0/openlineage", + // AUD0's OpenLineage ingest takes the tenant as a QUERY PARAM (verified + // against src/api/routes/openlineage.ts), not a body field. + query: { tenant_id: tenantId, app_id: appId }, + context, + headers: { "X-Tenant-Id": tenantId, "X-Actor-Id": appId }, + body: event, + acceptStatuses: [200], + }); + return (res.json ?? { + tenant_id: tenantId, + run_id: event.run.runId, + job: `${event.job.namespace}/${event.job.name}`, + event_id: "", + }) as Aud0OpenLineageAck; + } + + async ingestLineageEvent(event: Aud0LineageEvent, context?: SiaxRequestContext): Promise { + await this.ingestOpenLineageEvent(event.tenant_id, event.app_id, legacyLineageToOpenLineage(event), context); + return event; } } diff --git a/src/clients/cl0ud-client.ts b/src/clients/cl0ud-client.ts index adc8798..3210b3c 100644 --- a/src/clients/cl0ud-client.ts +++ b/src/clients/cl0ud-client.ts @@ -1,36 +1,39 @@ /** * src/clients/cl0ud-client.ts * ============================ - * 0pt's ONLY path to the CL0UD control-plane policy decision point: - * evaluatePolicy -> POST {baseUrl}/v1/cl0ud/policies/evaluate + * 0pt's ONLY path to the CL0UD control-plane policy decision point. * - * Every side-effecting 0pt capability re-consults CL0UD before acting (per - * docs/PRODUCT_PLAN.md §4.1) -- document-extraction-service.ts, - * iceberg-write-service.ts, external-writeback-service.ts -- so this is the - * single choke point for that. Never bypassed: a `deny` or - * `approval_required` decision always aborts the caller, even when an - * upstream gate (e.g. ACT0's own Approval Engine) already ran; see - * external-writeback-service.ts's module doc comment for why that specific - * re-check matters. + * REWRITTEN 2026-08-31 against CL0UD's REAL wire contract (cl0ud main, + * `packages/contract/openapi.yaml` + `apps/console/app/api/policy/evaluate/ + * route.ts`, verified this session): * - * Convention (identical to aud0-client.ts / n0d-client.ts / st0re-client.ts): - * when no base URL is configured the client runs in LOCAL PASS-THROUGH mode -- - * it returns a deterministic `allow` decision WITHOUT any network call, so - * unit tests and local dev are hermetic. Every 0pt service that calls - * evaluatePolicy() treats anything other than "allow" as fatal, so a mock that - * defaulted to "deny" would make every unconfigured-CL0UD path unusable; - * tests/p0/external-writeback-service.test.ts exercises "deny" and - * "approval_required" explicitly via its own fetch stub against an HTTP client - * instance, not this pass-through. + * evaluatePolicy -> POST {baseUrl}/api/policy/evaluate + * listCapabilities -> GET {baseUrl}/api/capabilities * - * This is a dev-mode default, NOT a security control. Any real deployment MUST - * set CL0UD_URL so decisions come from the real policy engine. The pass-through - * never invents a `deny`/`approval_required` -- it only ever allows, and it - * stamps a clearly local-looking decision id. + * The earlier client POSTed snake_case to `/v1/cl0ud/policies/evaluate` — a + * path that has never existed on CL0UD. That was exactly the MOCK_ONLY trap + * the Master-DoD audit predicted: the mock worked, the HTTP path had never + * been exercised against the real contract. The real contract is camelCase, + * envelope `{ data, meta }`, decision ∈ {allow, deny} plus a separate + * `requiresApproval` flag (allow+requiresApproval = route into approval, NOT + * a deny). 0pt maps that pair onto its historical three-value + * `PolicyDecisionValue` so existing call sites keep their exact semantics: + * anything other than plain "allow" aborts the caller. + * + * Production fallback policy (Master-DoD §3/§10): `createCl0udClient()` + * without a base URL THROWS `SiaxError("DEPENDENCY_UNAVAILABLE")` in a + * production runtime (NODE_ENV=production). The allow-only local + * pass-through survives ONLY for non-production runtimes (unit tests, local + * dev) — it never invents a deny, and it stamps a clearly local decision id. + * Policy itself remains fail-closed: a configured CL0UD answering 200 with a + * body missing `decision` is read as deny, never allow. */ import crypto from "crypto"; +import { SiaxHttp } from "./http"; +import { resolveDependencyBaseUrl } from "../platform/dependency-mode"; +import type { SiaxRequestContext } from "../platform/siax-context"; -/** The decision vocabulary itself. */ +/** The decision vocabulary 0pt call sites consume (unchanged). */ export type PolicyDecisionValue = "allow" | "deny" | "approval_required"; export interface EvaluatePolicyInput { @@ -43,59 +46,122 @@ export interface EvaluatePolicyInput { /** Risk level L0–L5 per the SIAX Cloud risk taxonomy. */ risk_level: string; correlation_id?: string; + /** + * The CL0UD actor descriptor. 0pt calls CL0UD as a platform service, and + * cl0ud's resolve-actor only lets an OPERATOR principal name an arbitrary + * actor — default is therefore `{ kind: "operator", role: "member" }`. + */ + actor?: { kind: "customer" | "operator"; role: "owner" | "admin" | "member" | "viewer" }; } -/** The decision record CL0UD returns. */ +/** The decision record 0pt call sites consume (unchanged shape). */ export interface PolicyDecision { decision: PolicyDecisionValue; decision_id: string; reason?: string; + /** CL0UD's deny code when decision = "deny" (e.g. rbac_forbidden). */ + deny_code?: string; } /** Alias so both historical import names resolve to the same shape. */ export type PolicyResult = PolicyDecision; +/** One CL0UD capability-registry entry (discovery API, tolerant-reader subset). */ +export interface Cl0udCapability { + name: string; + version: string; + owner: string; + status?: "beta" | "active" | "deprecated" | "retired"; + deprecation?: { since: string; replacement?: string; sunsetAt?: string; note?: string }; + requiredEntitlement?: string; + surfaces?: string[]; + [extra: string]: unknown; +} + export interface Cl0udClient { - evaluatePolicy(input: EvaluatePolicyInput): Promise; + evaluatePolicy(input: EvaluatePolicyInput, context?: SiaxRequestContext): Promise; + listCapabilities( + filter?: { owner?: string; surface?: string; status?: string; version?: string }, + context?: SiaxRequestContext + ): Promise; } -export function createCl0udClient(baseUrl?: string): Cl0udClient { - if (!baseUrl) return new LocalAllowCl0udClient(); - return new HttpCl0udClient(baseUrl); +export function createCl0udClient(baseUrl?: string, opts?: { token?: string }): Cl0udClient { + const resolved = resolveDependencyBaseUrl("cl0ud", baseUrl ?? process.env.CL0UD_URL); + if (!resolved) return new LocalAllowCl0udClient(); + return new HttpCl0udClient(resolved, opts?.token ?? process.env.CL0UD_SERVICE_TOKEN); } -/** No CL0UD_URL configured: allow-only local pass-through (see module doc comment). */ +/** + * Non-production runtimes only (the factory has already thrown in + * production): allow-only local pass-through, empty capability catalog. + */ class LocalAllowCl0udClient implements Cl0udClient { async evaluatePolicy(_input: EvaluatePolicyInput): Promise { return { decision: "allow", decision_id: `pdec_local_${crypto.randomUUID()}` }; } + async listCapabilities(): Promise { + return []; + } } class HttpCl0udClient implements Cl0udClient { - private readonly baseUrl: string; + private readonly http: SiaxHttp; - constructor(baseUrl: string) { - this.baseUrl = baseUrl.replace(/\/+$/, ""); + constructor(baseUrl: string, token?: string) { + this.http = new SiaxHttp({ dependency: "cl0ud", baseUrl, token }); } - async evaluatePolicy(input: EvaluatePolicyInput): Promise { - const res = await fetch(`${this.baseUrl}/v1/cl0ud/policies/evaluate`, { + async evaluatePolicy(input: EvaluatePolicyInput, context?: SiaxRequestContext): Promise { + const res = await this.http.request({ method: "POST", - headers: { "Content-Type": "application/json" }, - body: JSON.stringify(input), + path: "/api/policy/evaluate", + context, + body: { + capability: input.capability_id, + actor: input.actor ?? { kind: "operator", role: "member" }, + tenantId: input.tenant_id, + projectId: input.project_id, + surface: "api", + resource: { type: input.resource_type, id: input.resource_id }, + ...(input.correlation_id ? { correlationId: input.correlation_id } : {}), + }, }); - if (!res.ok) { - throw new Error(`CL0UD policy evaluate error: ${res.status} ${await res.text().catch(() => "")}`); + + const data = (res.json as { data?: Record } | undefined)?.data; + const rawDecision = data?.decision; + // FAIL CLOSED: 200 with a missing/unknown decision is a deny, never allow. + let decision: PolicyDecisionValue = "deny"; + if (rawDecision === "allow") { + decision = data?.requiresApproval === true ? "approval_required" : "allow"; + } else if (rawDecision === "deny") { + decision = "deny"; } - const body = (await res.json()) as Partial; - // FAIL CLOSED. A configured CL0UD that answers 200 with a body missing - // `decision` must not be read as an allow -- callers only special-case - // "deny"/"approval_required", so an `undefined` decision would slip - // through as if it had been permitted. return { - decision: (body.decision ?? "deny") as PolicyDecisionValue, - decision_id: body.decision_id ?? `pdec_${crypto.randomUUID()}`, - reason: body.reason, + decision, + decision_id: + typeof data?.decisionId === "string" ? data.decisionId : `pdec_${crypto.randomUUID()}`, + reason: typeof data?.reason === "string" ? data.reason : undefined, + deny_code: typeof data?.denyCode === "string" ? data.denyCode : undefined, }; } + + async listCapabilities( + filter?: { owner?: string; surface?: string; status?: string; version?: string }, + context?: SiaxRequestContext + ): Promise { + const res = await this.http.request({ + method: "GET", + path: "/api/capabilities", + context, + query: { + owner: filter?.owner, + surface: filter?.surface, + status: filter?.status, + version: filter?.version, + }, + }); + const data = (res.json as { data?: unknown } | undefined)?.data; + return Array.isArray(data) ? (data as Cl0udCapability[]) : []; + } } diff --git a/src/clients/http.ts b/src/clients/http.ts new file mode 100644 index 0000000..2816877 --- /dev/null +++ b/src/clients/http.ts @@ -0,0 +1,117 @@ +/** + * src/clients/http.ts + * ==================== + * Shared HTTP core for 0pt's four platform clients (cl0ud/st0re/n0d/aud0). + * One place for the behaviours Master-DoD §6/§10 require of every + * cross-product call: + * + * - request timeout (no hung platform call can wedge a capability), + * - typed `SiaxError` mapping from upstream status codes (retryable vs + * permanent explicit, correlation id carried, no raw upstream body leaked + * into the error message), + * - canonical SIAX context propagation headers (src/platform/siax-context.ts) + * plus optional service `Authorization` bearer (never the end-user token), + * - JSON body handling. + * + * Each client keeps its own wire mapping (the four dependencies genuinely + * differ: ST0RE is camelCase + X-Tenant-Id/X-Actor-Id, AUD0 is snake_case, + * CL0UD wraps in a `{ data, meta }` envelope, N0D is snake_case + 202) — this + * module owns only the transport discipline they share. + */ +import { SiaxError, siaxErrorCodeForUpstreamStatus } from "../platform/errors"; +import { toPropagationHeaders, type SiaxRequestContext } from "../platform/siax-context"; + +export interface SiaxHttpOptions { + /** Dependency name for error attribution, e.g. "st0re". */ + dependency: string; + baseUrl: string; + /** Service bearer token (machine identity). Optional — some deployments gate by network + headers. */ + token?: string; + /** Per-request timeout in ms. Default 15_000. */ + timeoutMs?: number; +} + +export interface SiaxRequestOptions { + method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE"; + path: string; + /** Query string parameters (skipped when undefined). */ + query?: Record; + body?: unknown; + /** Canonical SIAX context — serialized to propagation headers when present. */ + context?: SiaxRequestContext; + /** Extra headers (e.g. ST0RE's X-Idempotency-Key). Applied last. */ + headers?: Record; + /** Statuses the caller handles itself (returned, not thrown). */ + acceptStatuses?: number[]; +} + +export interface SiaxHttpResponse { + status: number; + /** Parsed JSON body, or undefined when the body was empty/non-JSON. */ + json: unknown; +} + +export class SiaxHttp { + private readonly dependency: string; + private readonly baseUrl: string; + private readonly token?: string; + private readonly timeoutMs: number; + + constructor(opts: SiaxHttpOptions) { + this.dependency = opts.dependency; + this.baseUrl = opts.baseUrl.replace(/\/+$/, ""); + this.token = opts.token; + this.timeoutMs = opts.timeoutMs ?? 15_000; + } + + async request(opts: SiaxRequestOptions): Promise { + const url = new URL(`${this.baseUrl}${opts.path}`); + for (const [k, v] of Object.entries(opts.query ?? {})) { + if (v !== undefined) url.searchParams.set(k, v); + } + + const headers: Record = { "Content-Type": "application/json" }; + if (this.token) headers["Authorization"] = `Bearer ${this.token}`; + if (opts.context) Object.assign(headers, toPropagationHeaders(opts.context)); + Object.assign(headers, opts.headers ?? {}); + + const correlationId = opts.context?.correlationId; + let res: Response; + try { + // NOTE: fetch is called with a STRING (not a URL object) so test fetch + // stubs that inspect `url.includes(...)` keep working. + res = await fetch(url.toString(), { + method: opts.method, + headers, + body: opts.body === undefined ? undefined : JSON.stringify(opts.body), + signal: AbortSignal.timeout(this.timeoutMs), + }); + } catch (cause) { + // Network failure / timeout: the dependency is unavailable — retryable. + throw new SiaxError( + "DEPENDENCY_UNAVAILABLE", + this.dependency, + `${opts.method} ${opts.path} failed to reach ${this.dependency} (${cause instanceof Error ? cause.name : "fetch error"})`, + { correlationId, cause } + ); + } + + if (!res.ok && !(opts.acceptStatuses ?? []).includes(res.status)) { + // Read the upstream machine-readable code when present, but never embed + // the raw body in the error (§6: no sensitive internals). + const upstream = (await res.json().catch(() => undefined)) as + | { error?: { code?: string; message?: string } } + | undefined; + const upstreamCode = upstream?.error?.code; + throw new SiaxError( + siaxErrorCodeForUpstreamStatus(res.status), + this.dependency, + `${opts.method} ${opts.path} → HTTP ${res.status}${upstreamCode ? ` (${upstreamCode})` : ""}`, + { correlationId } + ); + } + + const json = (await res.json().catch(() => undefined)) as unknown; + return { status: res.status, json }; + } +} diff --git a/src/clients/n0d-client.ts b/src/clients/n0d-client.ts index 7fc4115..f650a40 100644 --- a/src/clients/n0d-client.ts +++ b/src/clients/n0d-client.ts @@ -1,55 +1,114 @@ /** * src/clients/n0d-client.ts * ========================== - * 0pt's ONLY path for REQUESTING heavy compute jobs from N0D (the Compute OS). - * 0pt REQUESTS jobs; it never executes heavy work in-process and never owns - * N0D's scheduling/node/GPU decisions -- it submits a job and holds only the - * returned `job_id` (docs/11-lakehouse-write-plan.md item 7, - * docs/P0_QUERY_SOURCE_FLOW.md, and see - * `IcebergWriteService.requestIcebergWrite({ heavy: true })` for the concrete - * example this client backs): - * createJob -> POST {baseUrl}/v1/n0d/jobs + * 0pt's ONLY path for REQUESTING heavy compute jobs from N0D (the Compute + * OS). 0pt requests jobs and holds the returned `job_id`; it never executes + * heavy work in-process and never owns N0D's scheduling decisions. * - * Convention (identical to aud0-client.ts / cl0ud-client.ts / st0re-client.ts - * / st0re-lakehouse-client.ts): when no base URL is configured the client - * returns a deterministic in-memory MOCK job (id prefixed "mock_job_", the - * prefix tests/p0/iceberg-write-service.test.ts and - * tests/p0/document-capture-mailbox.test.ts already assert on) with NO network - * call, so unit tests stay hermetic. The mock never actually runs anything; a - * real deployment sets N0D_URL to submit against the live scheduler. + * REWRITTEN 2026-08-31 against N0D's REAL wire contract (sax3l/n0d branch + * feat/siax-platforms-p0-compute-os, `src/api/schemas.ts` createJobSchema + + * `src/api/mappers.ts` jobRecordToWire + `src/api/routes/job-lifecycle.ts`, + * verified this session): + * + * createJob -> POST {baseUrl}/v1/n0d/jobs (202 Accepted) + * getJob -> GET {baseUrl}/v1/n0d/jobs/:jobId + * getJobResult -> GET {baseUrl}/v1/n0d/jobs/:jobId/result + * + * Real-contract facts encoded here: + * - required create fields: job_type, capability_id, tenant_id, + * required_role (enum), resource_requirements {cpu, memory_gb, disk_gb}; + * - idempotency is BODY-ONLY (`idempotency_key`; there is no + * Idempotency-Key header on N0D) — same-tenant replay returns the + * existing record, foreign-tenant probe is a 404 (no existence oracle); + * - completion can be pushed as CloudEvents to `callback_url` + * (io.siax.n0d.job.*.v1) or polled via getJob/getJobResult; + * - the legacy fields this client used to send (`requested_by_app_id`, + * `required_node_roles[]`, `resource_profile`, `output_artifact_type`, + * `risk_level`) are NOT part of N0D's create schema. They remain + * accepted on the 0pt-side input for call-site stability and are MAPPED + * (documented per field below); tests/contracts/n0d-client.contract.test.ts + * pins the wire shape. + * + * Production fallback policy (Master-DoD §3/§10): no base URL in a + * production runtime throws `SiaxError("DEPENDENCY_UNAVAILABLE")` at + * construction. The in-memory mock (ids prefixed "mock_job_") survives only + * for non-production runtimes; it never runs anything. */ import crypto from "crypto"; +import { SiaxHttp } from "./http"; +import { resolveDependencyBaseUrl } from "../platform/dependency-mode"; +import type { SiaxRequestContext } from "../platform/siax-context"; + +/** N0D node roles (verbatim from n0d's createJobSchema). */ +export type N0dRequiredRole = + | "control_plane" + | "ai_gpu" + | "compute_general" + | "storage" + | "shared_utility"; + +/** N0D resource requirements (verbatim from n0d's createJobSchema). */ +export interface N0dResourceRequirements { + cpu: number; + memory_gb: number; + gpu?: number; + vram_gb?: number; + disk_gb: number; +} + +/** + * Named resource profiles 0pt uses when a call site does not spell out raw + * requirements. The mapping is 0pt-owned (N0D takes only raw numbers). + */ +export const N0D_RESOURCE_PROFILES: Readonly> = { + small: { cpu: 1, memory_gb: 2, gpu: 0, disk_gb: 5 }, + standard: { cpu: 2, memory_gb: 4, gpu: 0, disk_gb: 10 }, + large: { cpu: 8, memory_gb: 16, gpu: 0, disk_gb: 50 }, + gpu_standard: { cpu: 4, memory_gb: 16, gpu: 1, vram_gb: 16, disk_gb: 50 }, +}; export interface N0dCreateJobInput { tenant_id: string; project_id: string; job_type: string; capability_id: string; + /** Mapped to wire `app_id`. */ requested_by_app_id: string; + /** Mapped to wire `requested_by`. */ requested_by_actor_id: string; input_artifact_ids?: string[]; + /** NOT on N0D's wire contract; folded into input artifact ids by callers that need it. */ input_dataset_ids?: string[]; + /** Mapped to wire `output_policy.artifact_type` (+ write_to_st0re: true). */ output_artifact_type: string; + /** Mapped to wire `requires_shared_backbone`. */ requires_backbone: boolean; + /** Drives the required_role default (ai_gpu when true) + resource profile default. */ requires_gpu: boolean; + /** Legacy multi-role list; first entry that matches N0D's enum wins as `required_role`. */ required_node_roles: string[]; + /** Named profile resolved via {@link N0D_RESOURCE_PROFILES} unless resource_requirements given. */ resource_profile: string; - /** Risk level L0–L5 per the SIAX Cloud risk taxonomy. */ + /** Risk level L0–L5. NOT on N0D's create schema (documented inert there); kept for 0pt audit emission. */ risk_level: string; correlation_id?: string; + /** Explicit raw requirements (wins over resource_profile). */ + resource_requirements?: N0dResourceRequirements; + /** Explicit role (wins over required_node_roles/requires_gpu inference). */ + required_role?: N0dRequiredRole; + priority?: "low" | "normal" | "high"; + timeout_seconds?: number; + max_retries?: number; + /** Body-only idempotency key (tenant-scoped on N0D's side). */ + idempotency_key?: string; + /** CloudEvents completion callback URL (must be on N0D's callback allowlist). */ + callback_url?: string; } /** Alias so both historical import names resolve to the same shape. */ export type CreateJobInput = N0dCreateJobInput; -/** - * N0D's real job lifecycle, taken verbatim from sax3l/n0d's own wire contract - * (`packages/schemas/n0d.job.schema.json`, which mirrors - * `src/contracts/job.contract.ts`). That schema names the field `status`, not - * `state`, and says explicitly: "Do not add 'succeeded' -- that is 'completed' - * under a different name." An earlier draft of this client used a five-value - * `state` field with `succeeded`; it was wrong against the real contract. - */ +/** N0D's real 13-state job lifecycle (verbatim; no `succeeded` state exists). */ export type N0dJobStatus = | "created" | "validated" @@ -68,52 +127,163 @@ export type N0dJobStatus = /** Alias kept for the older name used elsewhere in this repo's history. */ export type N0dJobState = N0dJobStatus; -export interface N0dJob extends Partial { +/** The wire job record (n0d jobRecordToWire; tolerant-reader subset). */ +export interface N0dJob { job_id: string; job_type: string; tenant_id: string; - project_id: string; + project_id?: string; status: N0dJobStatus; + capability_id?: string; + app_id?: string; + requested_by?: string; + resource_requirements?: N0dResourceRequirements; + assigned_node_id?: string | null; + placement_reason?: string | null; created_at: string; + updated_at?: string; + error?: string | null; +} + +/** GET /v1/n0d/jobs/:id/result (n0d job-lifecycle.ts). */ +export interface N0dJobResult { + job_id: string; + run_id?: string; + outcome?: "succeeded" | "failed" | "cancelled" | "expired"; + exit_code?: number | null; + result?: unknown; + error?: string | null; + metrics?: Record; + completed_at?: string; + input_artifacts?: { st0re_artifact_id: string; artifact_type?: string }[]; + output_artifacts?: { st0re_artifact_id: string; artifact_type?: string }[]; } export interface N0dClient { - createJob(input: N0dCreateJobInput): Promise; + createJob(input: N0dCreateJobInput, context?: SiaxRequestContext): Promise; + getJob(jobId: string, tenantId: string, context?: SiaxRequestContext): Promise; + getJobResult(jobId: string, tenantId: string, context?: SiaxRequestContext): Promise; } -export function createN0dClient(baseUrl?: string): N0dClient { - if (!baseUrl) return new MockN0dClient(); - return new HttpN0dClient(baseUrl); +export function createN0dClient(baseUrl?: string, opts?: { token?: string }): N0dClient { + const resolved = resolveDependencyBaseUrl("n0d", baseUrl ?? process.env.N0D_URL); + if (!resolved) return new MockN0dClient(); + return new HttpN0dClient(resolved, opts?.token ?? process.env.N0D_SERVICE_TOKEN); } -/** No N0D_URL configured: returns a deterministic mock job (see module doc comment). */ +const N0D_ROLE_VALUES: ReadonlySet = new Set([ + "control_plane", + "ai_gpu", + "compute_general", + "storage", + "shared_utility", +]); + +/** Resolve the wire `required_role` from the richer 0pt-side input. */ +export function resolveRequiredRole(input: N0dCreateJobInput): N0dRequiredRole { + if (input.required_role) return input.required_role; + const legacy = input.required_node_roles.find((r) => N0D_ROLE_VALUES.has(r)); + if (legacy) return legacy as N0dRequiredRole; + return input.requires_gpu ? "ai_gpu" : "compute_general"; +} + +/** Resolve the wire `resource_requirements` from the richer 0pt-side input. */ +export function resolveResourceRequirements(input: N0dCreateJobInput): N0dResourceRequirements { + if (input.resource_requirements) return input.resource_requirements; + const profile = N0D_RESOURCE_PROFILES[input.resource_profile]; + if (profile) return input.requires_gpu && !profile.gpu ? N0D_RESOURCE_PROFILES.gpu_standard : profile; + return input.requires_gpu ? N0D_RESOURCE_PROFILES.gpu_standard : N0D_RESOURCE_PROFILES.standard; +} + +/** Non-production runtimes only: deterministic mock job; runs nothing. */ class MockN0dClient implements N0dClient { + private readonly jobs = new Map(); + async createJob(input: N0dCreateJobInput): Promise { - return { - ...input, + const job: N0dJob = { job_id: `mock_job_${crypto.randomUUID()}`, + job_type: input.job_type, + tenant_id: input.tenant_id, + project_id: input.project_id, + capability_id: input.capability_id, + app_id: input.requested_by_app_id, + requested_by: input.requested_by_actor_id, + resource_requirements: resolveResourceRequirements(input), status: "queued", created_at: new Date().toISOString(), }; + this.jobs.set(job.job_id, job); + return job; + } + + async getJob(jobId: string, tenantId: string): Promise { + const job = this.jobs.get(jobId); + if (!job || job.tenant_id !== tenantId) { + throw new Error(`mock N0D: job ${jobId} not found`); + } + return job; + } + + async getJobResult(jobId: string, tenantId: string): Promise { + await this.getJob(jobId, tenantId); + throw new Error(`mock N0D: job ${jobId} has no result (mock jobs never run)`); } } class HttpN0dClient implements N0dClient { - private readonly baseUrl: string; + private readonly http: SiaxHttp; - constructor(baseUrl: string) { - this.baseUrl = baseUrl.replace(/\/+$/, ""); + constructor(baseUrl: string, token?: string) { + this.http = new SiaxHttp({ dependency: "n0d", baseUrl, token }); } - async createJob(input: N0dCreateJobInput): Promise { - const res = await fetch(`${this.baseUrl}/v1/n0d/jobs`, { + async createJob(input: N0dCreateJobInput, context?: SiaxRequestContext): Promise { + const res = await this.http.request({ method: "POST", - headers: { "Content-Type": "application/json" }, - body: JSON.stringify(input), + path: "/v1/n0d/jobs", + context, + headers: { "X-Tenant-Id": input.tenant_id }, + body: { + job_type: input.job_type, + capability_id: input.capability_id, + tenant_id: input.tenant_id, + project_id: input.project_id, + app_id: input.requested_by_app_id, + requested_by: input.requested_by_actor_id, + required_role: resolveRequiredRole(input), + resource_requirements: resolveResourceRequirements(input), + priority: input.priority ?? "normal", + requires_shared_backbone: input.requires_backbone, + ...(input.input_artifact_ids?.length ? { input: { artifact_ids: input.input_artifact_ids } } : {}), + output_policy: { write_to_st0re: true, artifact_type: input.output_artifact_type }, + ...(input.timeout_seconds ? { timeout_seconds: input.timeout_seconds } : {}), + ...(input.max_retries !== undefined ? { max_retries: input.max_retries } : {}), + ...(input.idempotency_key ? { idempotency_key: input.idempotency_key } : {}), + ...(input.callback_url ? { callback_url: input.callback_url } : {}), + ...(input.correlation_id ? { correlation_id: input.correlation_id } : {}), + }, + acceptStatuses: [202], }); - if (!res.ok) { - throw new Error(`N0D create-job error: ${res.status} ${await res.text().catch(() => "")}`); - } - return (await res.json()) as N0dJob; + return (res.json ?? {}) as N0dJob; + } + + async getJob(jobId: string, tenantId: string, context?: SiaxRequestContext): Promise { + const res = await this.http.request({ + method: "GET", + path: `/v1/n0d/jobs/${encodeURIComponent(jobId)}`, + context, + headers: { "X-Tenant-Id": tenantId }, + }); + return (res.json ?? {}) as N0dJob; + } + + async getJobResult(jobId: string, tenantId: string, context?: SiaxRequestContext): Promise { + const res = await this.http.request({ + method: "GET", + path: `/v1/n0d/jobs/${encodeURIComponent(jobId)}/result`, + context, + headers: { "X-Tenant-Id": tenantId }, + }); + return (res.json ?? {}) as N0dJobResult; } } diff --git a/src/clients/st0re-client.ts b/src/clients/st0re-client.ts index bd6ff08..9574e18 100644 --- a/src/clients/st0re-client.ts +++ b/src/clients/st0re-client.ts @@ -1,38 +1,45 @@ /** * src/clients/st0re-client.ts * ============================ - * 0pt's client for the generic ST0RE Artifact registry (snake_case wire - * shape), used by document-capture-service.ts and - * document-extraction-service.ts to record what they produced. Distinct from - * `./st0re-lakehouse-client.ts` (the camelCase /v1/st0re/lakehouse/* table - * registry -- see that file's own doc comment for why the two are kept - * separate). This one registers an artifact's METADATA: a pointer to where the - * bytes live (provider/bucket/key/region) plus content-type/size/checksum/ - * retention/PII/residency: + * 0pt's client for the generic ST0RE Artifact registry. Distinct from + * `./st0re-lakehouse-client.ts` (the /v1/st0re/lakehouse/* table registry). + * + * REWRITTEN 2026-08-31 against ST0RE's REAL wire contract (sax3l/st0re branch + * feat/siax-platforms-p0-storage-os, `src/api/routes/artifacts.ts` + + * `src/api/validation.ts` ArtifactInputSchema, verified this session): + * * createArtifact -> POST {baseUrl}/v1/st0re/artifacts/register * - * The route is `/v1/st0re/artifacts/register`, NOT `/v1/st0re/artifacts`. - * Verified against sax3l/st0re `src/api/routes/artifacts.ts`, where - * `/v1/st0re/artifacts` is registered as a GET-only list route and the POST - * handler lives on `.../register`. An earlier draft of this client POSTed to - * the bare collection path and would not have registered anything. + * The REAL request body is camelCase (`tenantId`, `artifactType`, + * `primaryObjectId`, ...), NOT the snake_case + `object_location{...}` shape + * this client used to send — that shape would have been a 400 against the + * live registry. Key contract facts encoded here: * - * KNOWN GAP (documented in src/adapters/local-blob-store.ts and - * src/services/document-capture-service.ts's own header): ST0RE does not yet - * expose a raw-bytes upload endpoint for 0pt to call, so the actual bytes are - * persisted by LocalBlobStore (interim) and only the resulting location is - * registered here as metadata. + * - required: tenantId, projectId, appId, artifactType, displayName, + * producedBy, primaryObjectId, schemaVersion, retentionPolicy, createdBy; + * - checksumSha256 is DE FACTO required when ST0RE cannot derive it from a + * known same-tenant object (0pt always sends it — it always has the + * checksum, and never wants the fail-closed 400); + * - primaryObjectId accepts the `s3:///` storage URI (0pt + * formats it from its bucket/key pair); + * - headers: X-Tenant-Id + X-Actor-Id are REQUIRED on every ST0RE route; + * idempotency via X-Idempotency-Key (201 new, 200 idempotent replay); + * - body tenantId is ignored server-side in favour of X-Tenant-Id (sent + * anyway to satisfy validation). * - * Convention (identical to aud0-client.ts / cl0ud-client.ts / n0d-client.ts / - * st0re-lakehouse-client.ts): when no base URL is configured the client - * returns a deterministic in-memory MOCK artifact (id prefixed - * "mock_artifact_", the prefix tests/p0/document-capture-mailbox.test.ts and - * tests/p0/document-extraction-never-fabricates.test.ts assert on) with NO - * network call, so unit tests stay hermetic -- but it persists nothing beyond - * the current process. A real deployment sets ST0RE_URL to register against - * the live artifact registry. + * The 0pt-side input keeps its historical snake_case field names so existing + * call sites stay stable; the wire mapping lives here and is pinned by + * tests/contracts/st0re-client.contract.test.ts. + * + * Production fallback policy (Master-DoD §3/§10): no base URL in a production + * runtime throws `SiaxError("DEPENDENCY_UNAVAILABLE")` at construction. The + * in-memory mock (ids prefixed "mock_artifact_") survives only for + * non-production runtimes. */ import crypto from "crypto"; +import { SiaxHttp } from "./http"; +import { resolveDependencyBaseUrl } from "../platform/dependency-mode"; +import type { SiaxRequestContext } from "../platform/siax-context"; export interface St0reObjectLocation { provider: string; @@ -57,6 +64,14 @@ export interface St0reArtifactInput { /** Risk level L0–L5 per the SIAX Cloud risk taxonomy. */ risk_level: string; correlation_id?: string; + /** Human-readable name; defaults to the object key's basename. */ + display_name?: string; + /** Artifact schema version; defaults to "v1". */ + schema_version?: string; + /** Registering actor; defaults to produced_by. */ + created_by?: string; + /** Tenant-scoped dedup key (ST0RE replays the existing artifact on 200). */ + idempotency_key?: string; } /** Alias so both historical import names resolve to the same shape. */ @@ -68,15 +83,16 @@ export interface St0reArtifact extends St0reArtifactInput { } export interface St0reClient { - createArtifact(input: St0reArtifactInput): Promise; + createArtifact(input: St0reArtifactInput, context?: SiaxRequestContext): Promise; } -export function createSt0reClient(baseUrl?: string): St0reClient { - if (!baseUrl) return new MockSt0reClient(); - return new HttpSt0reClient(baseUrl); +export function createSt0reClient(baseUrl?: string, opts?: { token?: string }): St0reClient { + const resolved = resolveDependencyBaseUrl("st0re", baseUrl ?? process.env.ST0RE_URL); + if (!resolved) return new MockSt0reClient(); + return new HttpSt0reClient(resolved, opts?.token ?? process.env.ST0RE_SERVICE_TOKEN); } -/** No ST0RE_URL configured: returns a deterministic mock artifact (see module doc comment). */ +/** Non-production runtimes only: deterministic in-memory mock artifact. */ class MockSt0reClient implements St0reClient { async createArtifact(input: St0reArtifactInput): Promise { return { @@ -88,21 +104,54 @@ class MockSt0reClient implements St0reClient { } class HttpSt0reClient implements St0reClient { - private readonly baseUrl: string; + private readonly http: SiaxHttp; - constructor(baseUrl: string) { - this.baseUrl = baseUrl.replace(/\/+$/, ""); + constructor(baseUrl: string, token?: string) { + this.http = new SiaxHttp({ dependency: "st0re", baseUrl, token }); } - async createArtifact(input: St0reArtifactInput): Promise { - const res = await fetch(`${this.baseUrl}/v1/st0re/artifacts/register`, { + async createArtifact(input: St0reArtifactInput, context?: SiaxRequestContext): Promise { + const storageUri = `s3://${input.object_location.bucket}/${input.object_location.key}`; + const keyBasename = input.object_location.key.split("/").pop() ?? input.object_location.key; + const actorId = input.created_by ?? input.produced_by; + + const res = await this.http.request({ method: "POST", - headers: { "Content-Type": "application/json" }, - body: JSON.stringify(input), + path: "/v1/st0re/artifacts/register", + context, + // ST0RE requires X-Tenant-Id + X-Actor-Id on every route; the SIAX + // propagation headers (x-tenant-id/x-actor-id) satisfy that when a + // context is supplied, and these explicit values win regardless. + headers: { + "X-Tenant-Id": input.tenant_id, + "X-Actor-Id": actorId, + ...(input.idempotency_key ? { "X-Idempotency-Key": input.idempotency_key } : {}), + }, + body: { + tenantId: input.tenant_id, + projectId: input.project_id, + appId: input.app_id, + artifactType: input.artifact_type, + displayName: input.display_name ?? keyBasename, + producedBy: input.produced_by, + primaryObjectId: storageUri, + schemaVersion: input.schema_version ?? "v1", + retentionPolicy: input.retention_policy, + createdBy: actorId, + checksumSha256: input.checksum_sha256, + piiLevel: input.pii_level, + dataResidency: input.data_residency, + ...(input.idempotency_key ? { idempotencyKey: input.idempotency_key } : {}), + }, + // 200 = idempotent replay of an existing artifact — a success here. + acceptStatuses: [200], }); - if (!res.ok) { - throw new Error(`ST0RE artifact registration error: ${res.status} ${await res.text().catch(() => "")}`); - } - return (await res.json()) as St0reArtifact; + + const body = (res.json ?? {}) as { artifactId?: string; createdAt?: number }; + return { + ...input, + artifact_id: body.artifactId ?? "", + created_at: body.createdAt ? new Date(body.createdAt).toISOString() : new Date().toISOString(), + }; } } diff --git a/src/lineage/lineage-emitter.ts b/src/lineage/lineage-emitter.ts new file mode 100644 index 0000000..b1cf9fa --- /dev/null +++ b/src/lineage/lineage-emitter.ts @@ -0,0 +1,113 @@ +/** + * src/lineage/lineage-emitter.ts + * =============================== + * 0pt's OpenLineage emitter (Master-DoD §10 Lineage). One narrow API for + * capability services to record "this run read X and produced Y" against + * AUD0's real OpenLineage ingest (`POST /v1/aud0/openlineage` — see + * src/clients/aud0-client.ts for the wire). + * + * Design points: + * - Deterministic runIds (caller-supplied), so an idempotent retry of a + * capability re-emits the SAME event and AUD0 dedups it instead of + * recording a phantom second run. + * - Canonical SIAX resource refs (`st0re:artifact:...`, `0pt:dataset:...`) + * go in dataset facets so evidence chains can be joined across products + * (§16 "Evidence chains: Link source → transform → model → decision"). + * - Emission is evidence of what already happened — a lineage POST failure + * is surfaced to the caller as a warning value, never an exception that + * rolls back the completed work. Callers that need hard evidence + * guarantees must use an outbox (tracked honestly in STATUS.md). + */ +import type { Aud0Client } from "../clients/aud0-client"; +import { + OPT_OPENLINEAGE_PRODUCER, + type OpenLineageDatasetRef, + type OpenLineageEventType, + type OpenLineageRunEvent, +} from "./openlineage"; + +export interface LineageEmitInput { + tenant_id: string; + project_id?: string; + /** The 0pt capability that ran, e.g. "0pt.quality.run.v1". Becomes job.name. */ + capability_id: string; + /** Deterministic run id (e.g. the run/version/export id being recorded). */ + run_id: string; + event_type: OpenLineageEventType; + /** ISO timestamp; defaults to now. */ + event_time?: string; + /** Canonical SIAX refs and/or plain names consumed by the run. */ + inputs?: LineageDatasetInput[]; + /** Canonical SIAX refs and/or plain names produced by the run. */ + outputs?: LineageDatasetInput[]; + correlation_id?: string; + /** Extra run facets (namespaced siax*). */ + run_facets?: Record; +} + +export interface LineageDatasetInput { + /** Human/system dataset name, e.g. "dataset/ds_x" or "opensearch/opt-companies__g2". */ + name: string; + /** Optional canonical SIAX resource ref for cross-product joining. */ + ref?: string; + namespace?: string; + facets?: Record; +} + +export interface LineageEmitResult { + emitted: boolean; + run_id: string; + /** Present when emission failed (AUD0 unreachable etc.). */ + warning?: string; +} + +const APP_ID = "0pt"; + +function toDatasetRef(d: LineageDatasetInput): OpenLineageDatasetRef { + return { + namespace: d.namespace ?? APP_ID, + name: d.name, + facets: { + ...(d.ref ? { siaxResourceRef: { ref: d.ref } } : {}), + ...(d.facets ?? {}), + }, + }; +} + +export class LineageEmitter { + constructor(private readonly aud0: Aud0Client) {} + + buildRunEvent(input: LineageEmitInput): OpenLineageRunEvent { + return { + eventType: input.event_type, + eventTime: input.event_time ?? new Date().toISOString(), + producer: OPT_OPENLINEAGE_PRODUCER, + run: { + runId: input.run_id, + facets: { + ...(input.correlation_id ? { siaxCorrelation: { correlation_id: input.correlation_id } } : {}), + ...(input.project_id ? { siaxProject: { project_id: input.project_id } } : {}), + ...(input.run_facets ?? {}), + }, + }, + job: { namespace: APP_ID, name: input.capability_id }, + inputs: (input.inputs ?? []).map(toDatasetRef), + outputs: (input.outputs ?? []).map(toDatasetRef), + }; + } + + /** Emit one run event. Never throws — see module doc comment. */ + async emit(input: LineageEmitInput): Promise { + const event = this.buildRunEvent(input); + try { + await this.aud0.ingestOpenLineageEvent(input.tenant_id, APP_ID, event); + return { emitted: true, run_id: input.run_id }; + } catch (err) { + return { + emitted: false, + run_id: input.run_id, + warning: `openlineage emission failed: ${err instanceof Error ? err.message : String(err)}`, + }; + } + } +} diff --git a/src/lineage/openlineage.ts b/src/lineage/openlineage.ts new file mode 100644 index 0000000..cf56317 --- /dev/null +++ b/src/lineage/openlineage.ts @@ -0,0 +1,50 @@ +/** + * src/lineage/openlineage.ts + * =========================== + * Minimal, spec-shaped OpenLineage types for 0pt's lineage emission + * (Master-DoD §10 "Lineage: emit OpenLineage-events till AUD0:s + * ingest-kontrakt", §16 "OpenLineage: Run/Job/Dataset ingest"). + * + * This is a deliberate SUBSET of the OpenLineage 1.x spec + * (https://openlineage.io/spec/2-0-2/OpenLineage.json): the fields AUD0's + * `/v1/aud0/openlineage` ingest reads (eventType, eventTime, run.runId, + * job.namespace/name, inputs[], outputs[], facets passed through opaquely). + * Facets are open `Record` — AUD0 stores them verbatim as + * evidence; custom SIAX facets are namespaced `siax*`. + */ + +export type OpenLineageEventType = "START" | "RUNNING" | "COMPLETE" | "ABORT" | "FAIL" | "OTHER"; + +export interface OpenLineageDatasetRef { + /** Dataset namespace, e.g. "0pt" or a source system identifier. */ + namespace: string; + /** Dataset name, e.g. "dataset/ds_x" or "opensearch/opt-search-companies". */ + name: string; + facets?: Record; +} + +export interface OpenLineageRunEvent { + eventType: OpenLineageEventType; + /** ISO-8601 timestamp of the state transition. */ + eventTime: string; + /** Producer URI identifying the emitting code base. */ + producer: string; + /** Spec schema URL — optional; AUD0 does not require it. */ + schemaURL?: string; + run: { + /** Stable run id — 0pt uses deterministic ids so re-emission dedups. */ + runId: string; + facets?: Record; + }; + job: { + /** Job namespace — 0pt emits its app id ("0pt"). */ + namespace: string; + /** Job name — the 0pt capability id, e.g. "0pt.dataset.version.v1". */ + name: string; + facets?: Record; + }; + inputs?: OpenLineageDatasetRef[]; + outputs?: OpenLineageDatasetRef[]; +} + +export const OPT_OPENLINEAGE_PRODUCER = "https://git.siax.io/sax3l/0pt"; diff --git a/src/platform/dependency-mode.ts b/src/platform/dependency-mode.ts new file mode 100644 index 0000000..385adfd --- /dev/null +++ b/src/platform/dependency-mode.ts @@ -0,0 +1,81 @@ +/** + * src/platform/dependency-mode.ts + * ================================ + * THE production mock-fallback kill switch (Master-DoD §3: "Ingen + * production-path faller tyst tillbaka till mock/in-memory", §10: "Production + * kan inte falla tillbaka till mock"). + * + * Before this module, every platform client in src/clients/* documented the + * same convention: "when no base URL is configured the client runs in + * LOCAL/MOCK/NOOP mode". That convention is fine for unit tests and local + * dev, and it is EXACTLY the silent-fallback failure mode the Master-DoD + * forbids in production. This module centralizes the decision so every + * factory makes it the same way: + * + * - production runtime + no URL → throw SiaxError DEPENDENCY_UNAVAILABLE + * at CONSTRUCTION time (fail hard, fail early — not on first call). + * - non-production + no URL → the factory may return its local/mock + * implementation (hermetic tests, local dev). + * - URL configured → real HTTP client, any runtime. + * + * "Production runtime" means NODE_ENV=production, the same switch the + * existing auth layer uses (src/auth/context.ts refuses AUTH_ENFORCE=false + * under NODE_ENV=production). There is deliberately NO override that lets + * production run on mocks: if a deployment genuinely wants a dependency off, + * that is a topology decision expressed by NOT calling the capability, never + * by a mock silently answering it. + */ +import { SiaxError } from "./errors"; + +/** True when this process is a production runtime. */ +export function isProductionRuntime(env: NodeJS.ProcessEnv = process.env): boolean { + return env.NODE_ENV === "production"; +} + +/** + * Resolve a dependency base URL for a client factory. + * + * Returns the URL (trimmed, no trailing slash) when configured. Returns + * `undefined` when unconfigured in a non-production runtime — the caller may + * then use its documented local/mock implementation. THROWS + * `SiaxError("DEPENDENCY_UNAVAILABLE")` when unconfigured in production. + */ +export function resolveDependencyBaseUrl( + dependency: string, + configuredUrl: string | undefined, + env: NodeJS.ProcessEnv = process.env +): string | undefined { + const url = configuredUrl?.trim(); + if (url) return url.replace(/\/+$/, ""); + if (isProductionRuntime(env)) { + throw new SiaxError( + "DEPENDENCY_UNAVAILABLE", + dependency, + `no base URL configured for required dependency "${dependency}" in a production runtime; ` + + `refusing to fall back to a mock/in-memory implementation (Master-DoD §3/§10)` + ); + } + return undefined; +} + +/** + * Same decision for stateful stores (Postgres-backed registries): production + * with no DATABASE_URL must fail hard rather than serve an in-memory Map. + */ +export function resolveStoreMode( + store: string, + databaseUrl: string | undefined, + env: NodeJS.ProcessEnv = process.env +): { mode: "postgres"; url: string } | { mode: "memory" } { + const url = databaseUrl?.trim(); + if (url) return { mode: "postgres", url }; + if (isProductionRuntime(env)) { + throw new SiaxError( + "DEPENDENCY_UNAVAILABLE", + store, + `no database configured for persistent store "${store}" in a production runtime; ` + + `refusing the in-memory fallback (Master-DoD §3/§10)` + ); + } + return { mode: "memory" }; +} diff --git a/src/platform/errors.ts b/src/platform/errors.ts new file mode 100644 index 0000000..68cf14e --- /dev/null +++ b/src/platform/errors.ts @@ -0,0 +1,122 @@ +/** + * src/platform/errors.ts + * ======================= + * The canonical SIAX cross-product error vocabulary (Master-DoD §6), mirrored + * from cl0ud's `packages/contract/src/request-context.ts` (`SIAX_ERROR_CODES` + * + `httpStatusForSiaxErrorCode`) under the same documented mirror posture as + * src/platform/siax-context.ts. tests/contracts/siax-context.contract.test.ts + * pins the full code list and status mapping. + * + * `SiaxError` is the typed error every 0pt platform client and capability + * service throws at a product boundary. Retryable vs permanent is explicit + * (§6: "Retryable vs permanent är explicit"), correlation id travels in the + * error (§6: "Correlation ID finns i felet"), and no sensitive internals are + * embedded — `detail` is a short operator-facing string, never a raw body. + */ + +export const SIAX_ERROR_CODES = [ + "UNAUTHENTICATED", + "AUTHORIZATION_DENIED", + "ENTITLEMENT_REQUIRED", + "CAPABILITY_UNAVAILABLE", + "QUOTA_EXCEEDED", + "RATE_LIMITED", + "INVALID_REQUEST", + "NOT_FOUND", + "CONFLICT", + "DEPENDENCY_UNAVAILABLE", + "RETRYABLE_FAILURE", + "PERMANENT_FAILURE", +] as const; + +/** One canonical SIAX error code. */ +export type SiaxErrorCode = (typeof SIAX_ERROR_CODES)[number]; + +/** Canonical HTTP status for a {@link SiaxErrorCode} (transport guidance, pinned to cl0ud). */ +export function httpStatusForSiaxErrorCode(code: SiaxErrorCode): number { + switch (code) { + case "UNAUTHENTICATED": + return 401; + case "AUTHORIZATION_DENIED": + return 403; + case "ENTITLEMENT_REQUIRED": + case "QUOTA_EXCEEDED": + return 402; + case "CAPABILITY_UNAVAILABLE": + return 404; + case "RATE_LIMITED": + return 429; + case "INVALID_REQUEST": + return 400; + case "NOT_FOUND": + return 404; + case "CONFLICT": + return 409; + case "DEPENDENCY_UNAVAILABLE": + case "RETRYABLE_FAILURE": + return 503; + case "PERMANENT_FAILURE": + return 500; + default: { + const _never: never = code; + return _never; + } + } +} + +/** Whether a caller may retry the failed operation (with its idempotency key). */ +export function isRetryableSiaxErrorCode(code: SiaxErrorCode): boolean { + return code === "DEPENDENCY_UNAVAILABLE" || code === "RETRYABLE_FAILURE" || code === "RATE_LIMITED"; +} + +/** Map an upstream HTTP status (from a SIAX dependency) onto the canonical vocabulary. */ +export function siaxErrorCodeForUpstreamStatus(status: number): SiaxErrorCode { + if (status === 400) return "INVALID_REQUEST"; + if (status === 401) return "UNAUTHENTICATED"; + if (status === 402) return "ENTITLEMENT_REQUIRED"; + if (status === 403) return "AUTHORIZATION_DENIED"; + if (status === 404) return "NOT_FOUND"; + if (status === 409) return "CONFLICT"; + if (status === 429) return "RATE_LIMITED"; + if (status === 501) return "CAPABILITY_UNAVAILABLE"; + if (status === 502 || status === 503 || status === 504) return "DEPENDENCY_UNAVAILABLE"; + if (status >= 500) return "RETRYABLE_FAILURE"; + return "PERMANENT_FAILURE"; +} + +/** The typed error thrown at 0pt product boundaries. */ +export class SiaxError extends Error { + readonly code: SiaxErrorCode; + /** Which dependency/capability produced the failure, e.g. "st0re", "0pt.search.query". */ + readonly source: string; + /** Correlation id of the failing operation, when known (§6). */ + readonly correlationId?: string; + readonly retryable: boolean; + readonly httpStatus: number; + + constructor( + code: SiaxErrorCode, + source: string, + detail: string, + opts?: { correlationId?: string; cause?: unknown } + ) { + super(`[${code}] ${source}: ${detail}`, { cause: opts?.cause }); + this.name = "SiaxError"; + this.code = code; + this.source = source; + this.correlationId = opts?.correlationId; + this.retryable = isRetryableSiaxErrorCode(code); + this.httpStatus = httpStatusForSiaxErrorCode(code); + } + + /** Structured log/JSON form. Never includes stack or raw upstream bodies. */ + toJSON(): Record { + return { + error: this.code, + source: this.source, + message: this.message, + retryable: this.retryable, + ...(this.correlationId ? { correlation_id: this.correlationId } : {}), + }; + } +} diff --git a/src/platform/resource-ref.ts b/src/platform/resource-ref.ts new file mode 100644 index 0000000..0637fc8 --- /dev/null +++ b/src/platform/resource-ref.ts @@ -0,0 +1,44 @@ +/** + * src/platform/resource-ref.ts + * ============================= + * Canonical SIAX resource references (Master-DoD §5): + * + * `::[@]` + * + * e.g. `st0re:artifact:art_x`, `aud0:evidence:ev_x`, `0pt:dataset:ds_x`, + * `0pt:dataset:ds_x@3`. No product needs another product's DB primary key; + * references are stable, resolvable through the owning capability, and + * authorization happens at dereference (never here — this module is pure + * parsing/formatting). + */ + +export interface SiaxResourceRef { + product: string; + resourceType: string; + resourceId: string; + version?: string; +} + +const REF_RE = /^([a-z0-9][a-z0-9-]*):([a-z0-9][a-z0-9_-]*):([^@\s:]+)(?:@([A-Za-z0-9._-]+))?$/; + +/** Format a canonical reference string. */ +export function formatResourceRef(ref: SiaxResourceRef): string { + const base = `${ref.product}:${ref.resourceType}:${ref.resourceId}`; + return ref.version ? `${base}@${ref.version}` : base; +} + +/** Parse a canonical reference string; returns undefined when malformed. */ +export function parseResourceRef(raw: string): SiaxResourceRef | undefined { + const m = REF_RE.exec(raw.trim()); + if (!m) return undefined; + return { product: m[1], resourceType: m[2], resourceId: m[3], ...(m[4] ? { version: m[4] } : {}) }; +} + +/** True when `raw` is a canonical reference for the given product/type. */ +export function isResourceRef(raw: string, product?: string, resourceType?: string): boolean { + const ref = parseResourceRef(raw); + if (!ref) return false; + if (product && ref.product !== product) return false; + if (resourceType && ref.resourceType !== resourceType) return false; + return true; +} diff --git a/src/platform/siax-context.ts b/src/platform/siax-context.ts new file mode 100644 index 0000000..448898c --- /dev/null +++ b/src/platform/siax-context.ts @@ -0,0 +1,104 @@ +/** + * 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_` 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 { + const h: Record = { + [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): 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; +} diff --git a/tests/p0/document-capture-mailbox.test.ts b/tests/p0/document-capture-mailbox.test.ts index 8f1180f..7539654 100644 --- a/tests/p0/document-capture-mailbox.test.ts +++ b/tests/p0/document-capture-mailbox.test.ts @@ -63,7 +63,7 @@ describe("DocumentCaptureService.captureFromMailbox", () => { ], }); } - if (url.includes("/v1/aud0/events") || url.includes("/v1/aud0/lineage/events")) { + if (url.includes("/v1/aud0/events") || url.includes("/v1/aud0/openlineage")) { aud0Calls.push({ url, body: init?.body ? JSON.parse(init.body as string) : null }); return jsonResponse({}); } @@ -97,9 +97,11 @@ describe("DocumentCaptureService.captureFromMailbox", () => { expect(captured).toBeTruthy(); expect(captured!.body.payload.filename).toBe("doc.pdf"); expect(captured!.body.capability_id).toBe("0pt.capture_document"); - const lineage = aud0Calls.find((c) => c.url.includes("lineage")); + // Lineage now goes to AUD0's REAL ingest contract: an OpenLineage + // RunEvent on /v1/aud0/openlineage. + const lineage = aud0Calls.find((c) => c.url.includes("openlineage")); expect(lineage).toBeTruthy(); - expect(lineage!.body.target_id).toBe(doc.document_id); + expect(lineage!.body.outputs[0].name).toContain(doc.document_id); }); it("skips non-PDF attachments and records per-message errors without aborting the whole run", async () => { diff --git a/tests/p0/document-extraction-never-fabricates.test.ts b/tests/p0/document-extraction-never-fabricates.test.ts index aacc526..fee8a20 100644 --- a/tests/p0/document-extraction-never-fabricates.test.ts +++ b/tests/p0/document-extraction-never-fabricates.test.ts @@ -97,7 +97,7 @@ describe("DocumentExtractionService — evidence-based extraction", () => { }, }); } - if (url.includes("/v1/aud0/events") || url.includes("/v1/aud0/lineage/events")) { + if (url.includes("/v1/aud0/events") || url.includes("/v1/aud0/openlineage")) { aud0Calls.push({ url, body: init?.body ? JSON.parse(init.body as string) : null }); return jsonResponse({}); } diff --git a/tests/p0/external-writeback-service.test.ts b/tests/p0/external-writeback-service.test.ts index 639aef7..57c3594 100644 --- a/tests/p0/external-writeback-service.test.ts +++ b/tests/p0/external-writeback-service.test.ts @@ -61,14 +61,26 @@ function baseRequest(overrides: Partial = {}): ExternalWri function stubCl0udAllowAndAud0(opts: { decision?: "allow" | "deny" | "approval_required" } = {}) { const aud0Calls: { url: string; body: any }[] = []; const fetchMock = vi.fn(async (url: string, init?: RequestInit) => { - if (url.includes("/v1/cl0ud/policies/evaluate")) { + // REAL CL0UD wire contract (cl0ud main): POST /api/policy/evaluate with a + // `{ data: { decision, requiresApproval, ... } }` envelope; there is no + // "approval_required" decision value on the wire — it is allow + + // requiresApproval, which 0pt's client maps back onto the historical + // three-value vocabulary. + if (url.includes("/api/policy/evaluate")) { + const wanted = opts.decision ?? "allow"; return jsonResponse({ - decision_id: "pdec_test", - decision: opts.decision ?? "allow", - reason: opts.decision === "deny" ? "test_deny" : opts.decision === "approval_required" ? "test_approval_required" : undefined, + data: { + decision: wanted === "deny" ? "deny" : "allow", + requiresApproval: wanted === "approval_required", + decisionId: "pdec_test", + reason: wanted === "deny" ? "test_deny" : wanted === "approval_required" ? "test_approval_required" : undefined, + }, + meta: {}, }); } - if (url.includes("/v1/aud0/events") || url.includes("/v1/aud0/lineage/events")) { + // REAL AUD0 lineage ingest is the OpenLineage endpoint (/v1/aud0/openlineage); + // /v1/aud0/lineage/events never existed on AUD0. + if (url.includes("/v1/aud0/events") || url.includes("/v1/aud0/openlineage")) { aud0Calls.push({ url, body: init?.body ? JSON.parse(init.body as string) : null }); return jsonResponse({}); } @@ -145,11 +157,15 @@ describe("ExternalWritebackService — successful write", () => { expect(writtenEvent!.body.risk_level).toBe("L4"); expect(writtenEvent!.body.payload.external_id).toBe("ext_1"); - const lineageEvent = aud0Calls.find((c) => c.url.includes("/lineage/")); + // Lineage now goes to AUD0's REAL ingest contract: an OpenLineage + // RunEvent on /v1/aud0/openlineage (the legacy source/target shape is + // converted by aud0-client's legacyLineageToOpenLineage). + const lineageEvent = aud0Calls.find((c) => c.url.includes("/openlineage")); expect(lineageEvent).toBeTruthy(); - expect(lineageEvent!.body.source_id).toBe("idem-1"); - expect(lineageEvent!.body.target_id).toBe("ext_1"); - expect(lineageEvent!.body.lineage_type).toBe("produced"); + expect(lineageEvent!.body.eventType).toBe("COMPLETE"); + expect(lineageEvent!.body.inputs[0].name).toContain("idem-1"); + expect(lineageEvent!.body.outputs[0].name).toContain("ext_1"); + expect(lineageEvent!.body.run.facets.siaxLegacyLineage.lineage_type).toBe("produced"); }); });