@sentropic/artifacts 0.1.3 → 0.2.0

package/l0-freeze/commit-contract.ts

@@ -0,0 +1,421 @@
+/**
+ * L0 frozen commit declaration (immo #861, ask 2 shape, spec r2 section 3.2).
+ *
+ * Frozen server-side public exports for the Radar acceptance target:
+ * request-bound invocation context, commit context, typed authorization
+ * decision with an opaque fence, opaque commit transaction and the
+ * coordinator role. Barrier points, lane lock order and app signatures
+ * follow in later slices. Runtime implementation lands in L3.
+ */
+
+import type {
+  CommandIdentity,
+  COMMAND_CODEC_VERSION,
+  EffectiveArtifactCommand,
+  InternalIdempotencyKey,
+} from './command-identity-contract.js';
+import type { ArtifactFailure, ArtifactOutcome, OrdinaryFailure } from './failure-contract.js';
+import type { CompiledArtifactsProfile, CompiledValidators } from './profile-contract.js';
+
+/** Version of the frozen commit-coordinator protocol. */
+export const COMMIT_PROTOCOL_VERSION = 'artifacts-commit/v1' as const;
+
+/** Outcome of a COMMIT acknowledgment wait. */
+export const COMMIT_STATES = ['not_committed', 'committed', 'unknown'] as const;
+
+export type CommitState = (typeof COMMIT_STATES)[number];
+
+/** Purpose of one guard invocation: final decision or replayed receipt. */
+export const COMMIT_PURPOSES = ['finalize', 'replay'] as const;
+
+export type CommitPurpose = (typeof COMMIT_PURPOSES)[number];
+
+/**
+ * Guard callback supplied by the trusted host through server context.
+ * The provider invokes it after lock, pool-connection and object waits,
+ * inside the finalization boundary, before committing success. No public
+ * caller supplies SQL or a connection through this seam.
+ */
+export type AuthorizeCommit = (
+  context: ArtifactCommitContext,
+  transaction: ArtifactCommitTransaction,
+) => Promise<ArtifactAuthorizationDecision>;
+
+/**
+ * Frozen server-created invocation context. Neither body fields nor
+ * mutable app-global state may supply it; every publish/ensure invocation
+ * carries a fresh context binding the verified actor, the trusted storage
+ * scope and the request-bound guard.
+ */
+export interface ArtifactInvocationContext {
+  readonly invocationId: string;
+  readonly actorId: string;
+  readonly storageScopeId: string;
+  readonly authorizeCommit: AuthorizeCommit;
+}
+
+/**
+ * Commit-time context passed to the guard after all waits. It adds the
+ * operation, artifact/binding identity, computed command identity, policy
+ * revision and purpose to the invocation. The fence below, minted by the
+ * transaction-bound policy participant, is the only usable allowed
+ * credential; it cannot be synthesized from the revision string.
+ */
+export interface ArtifactCommitContext {
+  readonly invocationId: string;
+  readonly actorId: string;
+  readonly storageScopeId: string;
+  readonly operation: string;
+  readonly artifactId: string;
+  readonly bindingId: string;
+  readonly commandIdentity: CommandIdentity;
+  readonly policyRevision: string;
+  readonly purpose: CommitPurpose;
+}
+
+declare const commitFenceBrand: unique symbol;
+
+/** Opaque fence minted by the transaction-bound policy participant. */
+export interface ArtifactAuthorizationFence {
+  readonly [commitFenceBrand]: true;
+  readonly fenceId: string;
+  readonly invocationId: string;
+  readonly policyRevision: string;
+  readonly transactionId: string;
+}
+
+/** Denial reasons for a refused finalization. */
+export type AuthorizationDenialReason =
+  | 'denied' | 'revoked' | 'expired' | 'invalid_object' | 'unavailable';
+
+/**
+ * Typed authorization decision. Never an unqualified boolean: an allowed
+ * decision carries a usable guarded fence, a denial carries a typed
+ * reason plus the public projection (code, status, retry). Entry rejection
+ * stays distinguishable from a refusal raised inside finalization.
+ */
+export type ArtifactAuthorizationDecision =
+  | { readonly allowed: true; readonly fence: ArtifactAuthorizationFence }
+  | {
+    readonly allowed: false;
+    readonly reason: AuthorizationDenialReason;
+    readonly publicCode: string;
+    readonly status: number;
+    readonly retriable: boolean;
+  };
+
+declare const commitTransactionBrand: unique symbol;
+
+/**
+ * Opaque transaction identity plus the host's registered
+ * transaction-bound policy/quota participant. It exposes no
+ * commit/rollback/release method to the guard. Policy registration and
+ * SQL table mapping are fixed at coordinator construction.
+ */
+export interface ArtifactCommitTransaction {
+  readonly [commitTransactionBrand]: true;
+  readonly transactionId: string;
+  readonly invocationId: string;
+  readonly policyRevision: string;
+  readonly participant: ArtifactCommitParticipant;
+}
+
+/**
+ * Transaction-bound policy/quota participant registered at coordinator
+ * construction. The guard reaches policy and quota reads only through
+ * this participant on its leased transaction; public tool callers never
+ * receive a connection or SQL capability.
+ */
+export interface ArtifactCommitParticipant {
+  readonly policyRevision: string;
+  readAdmission(input: AdmissionReadInput): Promise<AdmissionReadResult>;
+  reserveQuota(input: QuotaReserveInput): Promise<QuotaReserveResult>;
+}
+
+/** Policy read scoped to one guarded finalization attempt. */
+export interface AdmissionReadInput {
+  readonly operation: string;
+  readonly artifactId: string;
+  readonly bindingId: string;
+  readonly actorId: string;
+  readonly policyRevision: string;
+}
+
+/** Policy read result; denial carries the typed refusal reason. */
+export interface AdmissionReadResult {
+  readonly allowed: boolean;
+  readonly reason: AuthorizationDenialReason;
+}
+
+/** Quota reservation scoped to one guarded finalization attempt. */
+export interface QuotaReserveInput {
+  readonly storageScopeId: string;
+  readonly operation: string;
+  readonly bytes: number;
+}
+
+/** Quota reservation result for one guarded finalization attempt. */
+export interface QuotaReserveResult {
+  readonly reserved: boolean;
+}
+
+/**
+ * Coordinator role owning the atomic finalization unit. The optional
+ * test observer receives barrier arrivals below the app with invocation
+ * correlation; it can never mark an operation authorized or successful.
+ * `finalizeOperation` owns the complete unit (key lock, participant
+ * locks, guard, commit/rollback); `replayOperation` re-reads the winner
+ * under the key lock and returns it through a fresh guarded replay.
+ */
+export interface ArtifactCommitCoordinator {
+  readonly protocolVersion: typeof COMMIT_PROTOCOL_VERSION;
+  readonly guardedOperations: readonly string[];
+  readonly testObserver?: CommitBarrierObserver;
+  finalizeOperation(
+    input: FinalizationInput,
+  ): Promise<ArtifactOutcome<FinalizationRecord>>;
+  replayOperation(
+    input: ReplayInput,
+  ): Promise<ArtifactOutcome<FinalizationRecord>>;
+}
+
+/** Coordinator completion record for one finalized or replayed operation. */
+export interface FinalizationRecord {
+  readonly internalKey: InternalIdempotencyKey;
+  readonly commandHash: string;
+  readonly codecVersion: typeof COMMAND_CODEC_VERSION;
+  readonly replayed: boolean;
+}
+
+/** Finalization input: request, invocation context and effective command. */
+export interface FinalizationInput {
+  readonly request: HttpRequest;
+  readonly invocation: ArtifactInvocationContext;
+  readonly command: EffectiveArtifactCommand;
+}
+
+/** Guarded replay input: invocation context and the durable internal key. */
+export interface ReplayInput {
+  readonly invocation: ArtifactInvocationContext;
+  readonly internalKey: InternalIdempotencyKey;
+}
+
+/**
+ * Nine section 3.2 barrier points. Tests of actual contention hold the
+ * exact coordination/policy/quota/pointer row from a second raw client at
+ * these points; the coordinator rechecks authority after a resumed
+ * barrier. S3 preparation precedes the key-lock barrier.
+ */
+export const COMMIT_BARRIER_POINTS = [
+  'before_connection_acquire',
+  'before_key_lock',
+  'before_blob_put',
+  'after_blob_put_before_verify',
+  'before_blob_readback',
+  'before_finalization_row_lock',
+  'after_finalization_locks_before_guard',
+  'after_replay_lookup_before_guard',
+  'before_commit',
+] as const;
+
+export type CommitBarrierPoint = (typeof COMMIT_BARRIER_POINTS)[number];
+
+/**
+ * Test-only barrier seam. Bound once as the coordinator `testObserver`
+ * option; `waitUntilReached` resolves after arrival and `release`
+ * resumes only that invocation/point.
+ */
+export interface CommitBarrierObserver {
+  arrive(point: CommitBarrierPoint, invocationId: string): void;
+}
+
+export interface ArtifactCommitBarrier {
+  readonly observer: CommitBarrierObserver;
+  waitUntilReached(point: CommitBarrierPoint, invocationId: string): Promise<void>;
+  release(point: CommitBarrierPoint, invocationId: string): void;
+}
+
+export type CreateArtifactCommitBarrier = () => ArtifactCommitBarrier;
+
+/**
+ * A4 participant lock order inside the finalization transaction, after
+ * the key lock: binding identity, artifact/lifecycle row, ACL row,
+ * current-pointer row, host authority/revision rows, quota rows, then
+ * blob-reference/deletion-claim rows. Multiple identities within one
+ * class lock in stable bytewise order. Artifact/lifecycle, ACL, pointer
+ * and quota rows use FOR UPDATE; authority rows use FOR SHARE. Binding
+ * uniqueness uses its own coordination row even when caller keys differ.
+ */
+export const PARTICIPANT_LOCK_ORDER = [
+  'binding-identity',
+  'artifact-lifecycle',
+  'acl',
+  'current-pointer',
+  'authority-revision',
+  'quota',
+  'blob-reference-deletion-claim',
+] as const;
+
+export type ParticipantLockClass = (typeof PARTICIPANT_LOCK_ORDER)[number];
+
+/**
+ * Frozen finalization order (ask 2, protocol A4). The host guard runs
+ * after lock, connection and object waits, inside the finalization
+ * boundary, before any committed success.
+ */
+export const FINALIZATION_PHASES = [
+  'admit', 'prepare', 'lock', 'provision', 'guard', 'commit',
+] as const;
+
+export type FinalizationPhase = (typeof FINALIZATION_PHASES)[number];
+
+/**
+ * Residue a refused finalization must never leave committed: no new
+ * ready release, pointer advance, attached provenance, ACL/binding or
+ * lifecycle change, consumed quota or replayable success.
+ */
+export const REFUSAL_RESIDUE_FORBIDDEN = [
+  'ready-release', 'pointer-advance', 'attached-provenance',
+  'acl-binding-change', 'lifecycle-change', 'consumed-quota', 'replayable-success',
+] as const;
+
+export type RefusalResidue = (typeof REFUSAL_RESIDUE_FORBIDDEN)[number];
+
+/** Profiles requiring guarded writes must declare a coordinator at startup. */
+export interface CoordinatorRequirement {
+  readonly requiresCoordinator: true;
+  readonly guardedOperations: readonly string[];
+}
+
+/** Transport-free HTTP request shape consumed by the frozen app. */
+export interface HttpRequest {
+  readonly method: string;
+  readonly path: string;
+  readonly headers: Record<string, string>;
+  readonly body: unknown;
+}
+
+/** Transport-free HTTP response shape produced by the frozen app. */
+export interface HttpResponse {
+  readonly status: number;
+  readonly headers: Record<string, string>;
+  readonly body: unknown;
+}
+
+/** Required app dependencies: no automatic legacy fallback exists. */
+export const HTTP_APP_REQUIRED_DEPS = ['profile', 'coordinator'] as const;
+
+/**
+ * App dependencies. Omitted profile, coordinator or write guard fails
+ * closed; the old split finalizer is removed, never selected implicitly.
+ */
+export interface HttpAppDeps {
+  readonly profile: CompiledArtifactsProfile;
+  readonly coordinator: ArtifactCommitCoordinator;
+}
+
+/**
+ * Frozen app surface. `execute` is the sole execution path returning the
+ * shared outcome with invocation, commit-state and replay correlation;
+ * `handle` calls it once, then sanitizes with the outcome projector.
+ * Hosts needing accounting call `execute` and the projector themselves,
+ * never both methods. Reads/entry rejection use `not_committed`; write
+ * success uses `committed`.
+ */
+export interface ArtifactApp {
+  readonly selectedCapabilities: readonly string[];
+  execute(
+    request: HttpRequest,
+    invocation: ArtifactInvocationContext,
+  ): Promise<ArtifactOutcome<HttpResponse>>;
+  handle(
+    request: HttpRequest,
+    invocation: ArtifactInvocationContext,
+  ): Promise<HttpResponse>;
+}
+
+/** Sanitized projection from outcome to HTTP response. */
+export type ProjectArtifactHttpOutcome = (
+  outcome: ArtifactOutcome<HttpResponse>,
+) => HttpResponse;
+
+/**
+ * Compile-time freeze assertions (P1-1). Checked by `npm run freeze-types`;
+ * type-only and erased at runtime. Each `@ts-expect-error` below must stay
+ * consumed: if a forged literal ever compiles, the gate fails.
+ */
+
+// Forged fences/transactions never satisfy the opaque contracts.
+const _forgedFence = {
+  fenceId: 'fence-1',
+  invocationId: 'inv-1',
+  policyRevision: 'rev-1',
+  transactionId: 'tx-1',
+};
+// @ts-expect-error — fences are minted by the transaction-bound participant
+const _fenceForgery: ArtifactAuthorizationFence = _forgedFence;
+
+const _forgedTransaction = {
+  transactionId: 'tx-1',
+  invocationId: 'inv-1',
+  policyRevision: 'rev-1',
+};
+// @ts-expect-error — transactions are opened by the coordinator
+const _transactionForgery: ArtifactCommitTransaction = _forgedTransaction;
+
+// The guard reaches policy/quota only through the registered participant.
+type _ParticipantAccess = ArtifactCommitTransaction['participant'] extends ArtifactCommitParticipant
+  ? true
+  : never;
+const _participantAccess: _ParticipantAccess = true;
+
+// The coordinator exposes callable finalization and replay operations.
+type _FinalizeCallable = ArtifactCommitCoordinator['finalizeOperation'] extends (
+  input: FinalizationInput,
+) => Promise<ArtifactOutcome<FinalizationRecord>>
+  ? true
+  : never;
+const _finalizeCallable: _FinalizeCallable = true;
+
+type _ReplayCallable = ArtifactCommitCoordinator['replayOperation'] extends (
+  input: ReplayInput,
+) => Promise<ArtifactOutcome<FinalizationRecord>>
+  ? true
+  : never;
+const _replayCallable: _ReplayCallable = true;
+
+// Compiled profiles carry semantic validators for the lanes to consume.
+type _ValidatorsWired = CompiledArtifactsProfile['validators'] extends CompiledValidators
+  ? true
+  : never;
+const _validatorsWired: _ValidatorsWired = true;
+
+// Ordinary categories do not belong to the operational failure branch.
+const _ordinaryFields = {
+  kind: 'operational',
+  category: 'invalid_request',
+  httpStatus: 400,
+  publicCode: 'invalid_request',
+  retriable: false,
+  invocationId: 'inv-1',
+  operation: 'publish',
+  phase: 'entry',
+  commitState: 'not_committed',
+  cause: undefined,
+} as const;
+// @ts-expect-error — 'invalid_request' is an ordinary category, not operational
+const _ordinaryAsOperational: ArtifactFailure = _ordinaryFields;
+
+const _ordinaryPositive: OrdinaryFailure = {
+  kind: 'ordinary',
+  category: 'invalid_request',
+  httpStatus: 400,
+  publicCode: 'invalid_request',
+  retriable: false,
+  invocationId: 'inv-1',
+  operation: 'publish',
+  phase: 'entry',
+  commitState: 'not_committed',
+  cause: undefined,
+};
+const _ordinaryInOutcome: ArtifactOutcome<string> = { ok: false, failure: _ordinaryPositive };

package/l0-freeze/failure-contract.ts

@@ -0,0 +1,174 @@
+/**
+ * L0 frozen failure declaration (immo #861, ask 3 shape, spec r2 E2/E3).
+ *
+ * Stable internal outcome shape and category-to-public projection table.
+ * `capability_unselected` is a distinct pre-dispatch non-retriable 503
+ * with no write-ledger entry; the guard authority outage shares the
+ * commit category and ledger reason with policy denial but projects a
+ * retriable same-key 503. Driver detail stays in the private cause and
+ * never enters HTTP bodies, MCP results or metadata. The classifier and
+ * success replay flag land in L2.
+ */
+
+import type { CommitState } from './commit-contract.js';
+
+/**
+ * Internal failure categories, distinct from ordinary typed
+ * validation/not-found/gone outcomes whose existing public mappings
+ * remain supported.
+ */
+export const FAILURE_CATEGORIES = [
+  'capability_unselected', 'provider_unavailable', 'conflict',
+  'unauthorized_at_commit', 'provider_error',
+] as const;
+
+export type FailureCategory = (typeof FAILURE_CATEGORIES)[number];
+
+/**
+ * Frozen category-to-public projection (ask 3, table E2). `variant`
+ * selects the projection row inside one category. An absent
+ * `radarLedgerReason` means the rejection happens before dispatch and
+ * creates no write-commit ledger entry. `phase`/`commitState` are the
+ * projection defaults; the per-incident phase travels on ArtifactFailure.
+ */
+export interface FailureProjection {
+  readonly category: FailureCategory;
+  readonly variant?: string;
+  readonly httpStatus: number;
+  readonly publicCode: string;
+  readonly radarLedgerReason?: string;
+  readonly retriable: boolean;
+  readonly phase: string;
+  readonly commitState: CommitState;
+}
+
+export const ORDINARY_FAILURE_CATEGORIES = [
+  'invalid_request', 'not_found', 'gone', 'unprocessable', 'verification_failed',
+] as const;
+
+export type OrdinaryFailureCategory = (typeof ORDINARY_FAILURE_CATEGORIES)[number];
+
+/**
+ * Frozen ordinary domain-failure projection. Ordinary validation,
+ * not-found, gone and verification outcomes are entry rejections: they
+ * never enter the write-commit ledger and keep the existing public
+ * mappings.
+ */
+export interface OrdinaryFailureProjection {
+  readonly category: OrdinaryFailureCategory;
+  readonly httpStatus: number;
+  readonly publicCode: string;
+  readonly retriable: false;
+  readonly phase: string;
+  readonly commitState: CommitState;
+}
+
+export const ORDINARY_FAILURE_PROJECTIONS: readonly OrdinaryFailureProjection[] = [
+  {
+    category: 'invalid_request', httpStatus: 400, publicCode: 'invalid_request',
+    retriable: false, phase: 'entry', commitState: 'not_committed',
+  },
+  {
+    category: 'not_found', httpStatus: 404, publicCode: 'not_found',
+    retriable: false, phase: 'entry', commitState: 'not_committed',
+  },
+  {
+    category: 'gone', httpStatus: 410, publicCode: 'gone',
+    retriable: false, phase: 'entry', commitState: 'not_committed',
+  },
+  {
+    category: 'unprocessable', httpStatus: 422, publicCode: 'unprocessable',
+    retriable: false, phase: 'entry', commitState: 'not_committed',
+  },
+  {
+    category: 'verification_failed', httpStatus: 422, publicCode: 'verification_failed',
+    retriable: false, phase: 'entry', commitState: 'not_committed',
+  },
+] as const;
+
+export const FAILURE_PROJECTIONS: readonly FailureProjection[] = [
+  {
+    category: 'capability_unselected', variant: 'unselected_operation',
+    httpStatus: 503, publicCode: 'capability_unavailable',
+    retriable: false, phase: 'selection', commitState: 'not_committed',
+  },
+  {
+    category: 'provider_unavailable', variant: 'dispatch_failure',
+    httpStatus: 503, publicCode: 'capability_unavailable',
+    radarLedgerReason: 'provider_unavailable',
+    retriable: true, phase: 'dispatch', commitState: 'not_committed',
+  },
+  {
+    category: 'conflict', variant: 'key_contention',
+    httpStatus: 409, publicCode: 'conflict',
+    radarLedgerReason: 'provider_conflict',
+    retriable: false, phase: 'lock', commitState: 'not_committed',
+  },
+  {
+    category: 'unauthorized_at_commit', variant: 'policy_denial',
+    httpStatus: 403, publicCode: 'access_denied',
+    radarLedgerReason: 'unauthorized_at_commit',
+    retriable: false, phase: 'guard', commitState: 'not_committed',
+  },
+  {
+    category: 'unauthorized_at_commit', variant: 'authority_unavailable',
+    httpStatus: 503, publicCode: 'capability_unavailable',
+    radarLedgerReason: 'unauthorized_at_commit',
+    retriable: true, phase: 'guard', commitState: 'not_committed',
+  },
+  {
+    category: 'provider_error', variant: 'unclassified',
+    httpStatus: 500, publicCode: 'internal_error',
+    radarLedgerReason: 'provider_error',
+    retriable: false, phase: 'operation', commitState: 'not_committed',
+  },
+] as const;
+
+/** Classified internal failure with private cause and commit state. */
+export interface ArtifactFailure {
+  readonly kind: 'operational';
+  readonly category: FailureCategory;
+  readonly variant?: string;
+  readonly httpStatus: number;
+  readonly publicCode: string;
+  readonly retriable: boolean;
+  readonly invocationId: string;
+  readonly operation: string;
+  readonly phase: string;
+  readonly commitState: CommitState;
+  readonly cause: unknown;
+}
+
+/** Ordinary typed domain failure with retained private cause. */
+export interface OrdinaryFailure {
+  readonly kind: 'ordinary';
+  readonly category: OrdinaryFailureCategory;
+  readonly httpStatus: number;
+  readonly publicCode: string;
+  readonly retriable: false;
+  readonly invocationId: string;
+  readonly operation: string;
+  readonly phase: string;
+  readonly commitState: CommitState;
+  readonly cause: unknown;
+}
+
+/**
+ * Required success correlation fields: invocation identity, commit state
+ * and replay flag travel on every success alongside the result. Both HTTP
+ * and MCP consume this same result type.
+ */
+export const OUTCOME_SUCCESS_FIELDS = [
+  'ok', 'result', 'invocationId', 'commitState', 'replayed',
+] as const;
+
+/** Internal discriminated outcome shared by HTTP and MCP projections. */
+export type ArtifactOutcome<T> =
+  | {
+    readonly ok: true;
+    readonly result: T;
+    readonly invocationId: string;
+    readonly commitState: CommitState;
+    readonly replayed: boolean;
+  }
+  | { readonly ok: false; readonly failure: ArtifactFailure | OrdinaryFailure };