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:
co-authored by
Claude Fable 5
parent
00a1b3997d
commit
b7038d7675
+160
-56
@@ -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
@@ -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[]) : [];
|
||||
}
|
||||
}
|
||||
|
||||
@@ -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
@@ -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
@@ -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(),
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
@@ -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)}`,
|
||||
};
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -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";
|
||||
@@ -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" };
|
||||
}
|
||||
@@ -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 } : {}),
|
||||
};
|
||||
}
|
||||
}
|
||||
@@ -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;
|
||||
}
|
||||
@@ -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;
|
||||
}
|
||||
@@ -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({});
|
||||
}
|
||||
|
||||
@@ -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");
|
||||
});
|
||||
});
|
||||
|
||||
|
||||
Reference in New Issue
Block a user