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>
This commit is contained in:
Simon Axelsson
2026-08-31 16:35:01 +02:00
co-authored by Claude Fable 5
parent 00a1b3997d
commit b7038d7675
14 changed files with 1240 additions and 202 deletions
+160 -56
View File
@@ -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<string, unknown>`,
* 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<Aud0Event>;
ingestLineageEvent(event: Aud0LineageEvent): Promise<Aud0LineageEvent>;
/** 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<Aud0Event>;
ingestOpenLineageEvent(
tenantId: string,
appId: string,
event: OpenLineageRunEvent,
context?: SiaxRequestContext
): Promise<Aud0OpenLineageAck>;
/** @deprecated Legacy shim — converts to OpenLineage and posts to /v1/aud0/openlineage. */
ingestLineageEvent(event: Aud0LineageEvent, context?: SiaxRequestContext): Promise<Aud0LineageEvent>;
}
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:<runId>:<eventType>:<eventTime>` 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<Aud0Event> {
return event;
}
async ingestOpenLineageEvent(
tenantId: string,
_appId: string,
event: OpenLineageRunEvent
): Promise<Aud0OpenLineageAck> {
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<Aud0LineageEvent> {
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<Aud0Event> {
return this.post("/v1/aud0/events", event);
}
async ingestLineageEvent(event: Aud0LineageEvent): Promise<Aud0LineageEvent> {
return this.post("/v1/aud0/lineage/events", event);
}
private async post<T>(path: string, body: T): Promise<T> {
const res = await fetch(`${this.baseUrl}${path}`, {
async ingestEvent(event: Aud0Event, context?: SiaxRequestContext): Promise<Aud0Event> {
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<Aud0OpenLineageAck> {
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<Aud0LineageEvent> {
await this.ingestOpenLineageEvent(event.tenant_id, event.app_id, legacyLineageToOpenLineage(event), context);
return event;
}
}
+113 -47
View File
@@ -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<PolicyDecision>;
evaluatePolicy(input: EvaluatePolicyInput, context?: SiaxRequestContext): Promise<PolicyDecision>;
listCapabilities(
filter?: { owner?: string; surface?: string; status?: string; version?: string },
context?: SiaxRequestContext
): Promise<Cl0udCapability[]>;
}
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<PolicyDecision> {
return { decision: "allow", decision_id: `pdec_local_${crypto.randomUUID()}` };
}
async listCapabilities(): Promise<Cl0udCapability[]> {
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<PolicyDecision> {
const res = await fetch(`${this.baseUrl}/v1/cl0ud/policies/evaluate`, {
async evaluatePolicy(input: EvaluatePolicyInput, context?: SiaxRequestContext): Promise<PolicyDecision> {
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<string, unknown> } | 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<PolicyDecision>;
// 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<Cl0udCapability[]> {
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[]) : [];
}
}
+117
View File
@@ -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<string, string | undefined>;
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<string, string>;
/** 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<SiaxHttpResponse> {
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<string, string> = { "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 };
}
}
+214 -44
View File
@@ -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<Record<string, N0dResourceRequirements>> = {
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<N0dCreateJobInput> {
/** 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<string, number>;
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<N0dJob>;
createJob(input: N0dCreateJobInput, context?: SiaxRequestContext): Promise<N0dJob>;
getJob(jobId: string, tenantId: string, context?: SiaxRequestContext): Promise<N0dJob>;
getJobResult(jobId: string, tenantId: string, context?: SiaxRequestContext): Promise<N0dJobResult>;
}
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<string> = 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<string, N0dJob>();
async createJob(input: N0dCreateJobInput): Promise<N0dJob> {
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<N0dJob> {
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<N0dJobResult> {
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<N0dJob> {
const res = await fetch(`${this.baseUrl}/v1/n0d/jobs`, {
async createJob(input: N0dCreateJobInput, context?: SiaxRequestContext): Promise<N0dJob> {
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<N0dJob> {
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<N0dJobResult> {
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;
}
}
+91 -42
View File
@@ -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://<bucket>/<key>` 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<St0reArtifact>;
createArtifact(input: St0reArtifactInput, context?: SiaxRequestContext): Promise<St0reArtifact>;
}
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<St0reArtifact> {
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<St0reArtifact> {
const res = await fetch(`${this.baseUrl}/v1/st0re/artifacts/register`, {
async createArtifact(input: St0reArtifactInput, context?: SiaxRequestContext): Promise<St0reArtifact> {
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(),
};
}
}
+113
View File
@@ -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<string, unknown>;
}
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<string, unknown>;
}
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<LineageEmitResult> {
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)}`,
};
}
}
}
+50
View File
@@ -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<string, unknown>` — 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<string, unknown>;
}
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<string, unknown>;
};
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<string, unknown>;
};
inputs?: OpenLineageDatasetRef[];
outputs?: OpenLineageDatasetRef[];
}
export const OPT_OPENLINEAGE_PRODUCER = "https://git.siax.io/sax3l/0pt";
+81
View File
@@ -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" };
}
+122
View File
@@ -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<string, unknown> {
return {
error: this.code,
source: this.source,
message: this.message,
retryable: this.retryable,
...(this.correlationId ? { correlation_id: this.correlationId } : {}),
};
}
}
+44
View File
@@ -0,0 +1,44 @@
/**
* src/platform/resource-ref.ts
* =============================
* Canonical SIAX resource references (Master-DoD §5):
*
* `<product>:<resourceType>:<resourceId>[@<version>]`
*
* 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;
}
+104
View File
@@ -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_<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;
}
+5 -3
View File
@@ -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 () => {
@@ -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({});
}
+25 -9
View File
@@ -61,14 +61,26 @@ function baseRequest(overrides: Partial<ExternalWriteRequest> = {}): 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");
});
});