@sentropic/artifacts 0.1.4 → 0.2.1

package/l0-freeze/profile-contract.ts

@@ -0,0 +1,219 @@
+/**
+ * L0 frozen profile declaration (immo #861, ask 1 shape, spec r2 section 2).
+ *
+ * Stable data shapes, bounds and version constants for explicit capability
+ * selection and the effective publication profile, plus the frozen
+ * provider-profile interfaces L1 compiles. No behavior: L1 wires these
+ * shapes into the factories.
+ */
+
+import type { EffectiveArtifactCommand } from './command-identity-contract.js';
+import type { JsonValue } from '../src/contracts.js';
+
+/** Version of the frozen effective-profile shape. */
+export const PROFILE_CONTRACT_VERSION = 'artifacts-profile/v1' as const;
+
+/** All fifteen existing tool names, frozen (L1 wires the compiler to this set). */
+export const KNOWN_ARTIFACT_TOOL_NAMES = [
+  'artifacts_get_template', 'artifacts_get_api_guide', 'artifacts_ensure',
+  'artifacts_publish', 'artifacts_create_upload', 'artifacts_commit_upload',
+  'artifacts_list', 'artifacts_get', 'artifacts_get_source', 'artifacts_fork',
+  'artifacts_set_access', 'artifacts_promote', 'artifacts_renew',
+  'artifacts_delete', 'artifacts_restore',
+] as const;
+
+export type KnownArtifactToolName = (typeof KNOWN_ARTIFACT_TOOL_NAMES)[number];
+
+/** Radar ask-1 selection: the only four tools the Radar host enables. */
+export const RADAR_SELECTED_TOOL_NAMES = [
+  'artifacts_ensure', 'artifacts_publish', 'artifacts_list', 'artifacts_get',
+] as const;
+
+export type RadarSelectedToolName = (typeof RADAR_SELECTED_TOOL_NAMES)[number];
+
+/**
+ * Frozen C2 capability routes: selected capability, provider route and
+ * Radar command. The adapter accepts exactly these four method/path
+ * combinations, not an arbitrary HTTP proxy.
+ */
+export const RADAR_OPERATION_ROUTES = [
+  { capability: 'artifacts_ensure', method: 'POST', path: '/ensure', command: 'ensure' },
+  { capability: 'artifacts_publish', method: 'POST', path: '/publish', command: 'publish' },
+  { capability: 'artifacts_list', method: 'POST', path: '/list', command: 'list' },
+  { capability: 'artifacts_get', method: 'GET', path: '/meta/{artifactId}', command: 'meta' },
+] as const;
+
+export type RadarOperationRoute = (typeof RADAR_OPERATION_ROUTES)[number];
+
+/** Host-bound invocation scope for the Radar selection. */
+export const RADAR_INVOCATION_SCOPE = 'immo:read' as const;
+
+/** Explicit capability selection: unknown and duplicate entries are rejected. */
+export interface ToolSelection {
+  readonly tools: readonly string[];
+}
+
+/** Closed effective-profile MIME allowlist for publish files. */
+export const PROFILE_TEXT_MIME_TYPES = [
+  'text/html', 'text/css', 'text/javascript', 'application/json',
+] as const;
+
+export type ProfileMimeType = (typeof PROFILE_TEXT_MIME_TYPES)[number];
+
+/** First path segments a publish file must never use. */
+export const PROFILE_RESERVED_FIRST_SEGMENTS = [
+  'api', '__artifacts', 'livez', 'health',
+] as const;
+
+/** Frozen C4 bounds (UTF-16 code units unless noted). */
+export const PROFILE_BOUNDS = {
+  bindingNameMinUnits: 1,
+  bindingNameMaxUnits: 128,
+  idempotencyKeyMaxUnits: 256,
+  publishFilesMin: 1,
+  publishFilesMax: 32,
+  maxDecodedFileBytes: 262144,
+  maxDecodedTotalBytes: 262144,
+  /** Candidate ceiling inherited from the existing provider validator. */
+  pathMaxBytes: 1024,
+  listLimitMin: 1,
+  listLimitMax: 100,
+  listLimitDefault: 20,
+  listOffsetDefault: 0,
+  /** The HTTP control route keeps its separate encoded-body budget. */
+  httpControlMaxEncodedBytes: 2 * 1024 * 1024,
+} as const;
+
+/** Inputs that participate in composition integrity evidence. */
+export const COMPOSITION_DIGEST_INPUTS = [
+  'selection', 'profile', 'providerContractRevisions',
+] as const;
+
+/** One operation profile inside the effective profile. */
+export interface OperationProfile {
+  readonly operation: string;
+  readonly limits: Record<string, number>;
+  readonly defaults: Record<string, JsonValue | undefined>;
+}
+
+/** Immutable versioned effective profile driving one composition. */
+export interface EffectiveProfile {
+  readonly version: typeof PROFILE_CONTRACT_VERSION;
+  readonly selection: ToolSelection;
+  readonly operations: readonly OperationProfile[];
+  readonly contractRevisions: Record<string, string>;
+  readonly profileDigest: string;
+}
+
+/**
+ * Frozen provider profile input: explicit selected tools, complete
+ * operation profiles and required contract versions. Unknown and
+ * duplicate entries are rejected; an empty selection exposes and
+ * executes nothing; a missing selection fails construction.
+ */
+export interface ArtifactProviderProfile {
+  readonly version: typeof PROFILE_CONTRACT_VERSION;
+  readonly selectedCapabilities: readonly string[];
+  readonly operations: readonly OperationProfile[];
+  readonly contractRevisions: Record<string, string>;
+}
+
+/**
+ * Compiled profile driving schema generation, validation, normalization,
+ * defaults, command hashing and runtime limits. Selection, full profile
+ * data and provider-contract revisions participate in the digest; a
+ * semantic-only change invalidates the evidence even when JSON Schema
+ * text is unchanged.
+ */
+export interface CompiledArtifactsProfile extends ArtifactProviderProfile {
+  readonly schemas: Record<string, Record<string, unknown>>;
+  readonly validators: CompiledValidators;
+  readonly profileDigest: string;
+}
+
+/**
+ * Compiled semantic validators and normalizers bound at profile compile
+ * time. L1 implements them against the frozen operation profiles; L2/L6
+ * consume them instead of reimplementing checks.
+ */
+export interface CompiledValidators {
+  readonly validateBindingName: (value: unknown) => boolean;
+  readonly validateCallerKey: (value: unknown) => boolean;
+  readonly validateFileEntry: (entry: unknown) => boolean;
+  readonly normalizeCommand: (command: unknown) => EffectiveArtifactCommand;
+}
+
+/** Compiler signature: L1 implements it against these frozen shapes. */
+export type CompileArtifactsProfile = (
+  input: ArtifactProviderProfile,
+) => CompiledArtifactsProfile;
+
+/**
+ * Semantic-only profile pair: identical expressible JSON Schema text with
+ * different effective semantics. The digest MUST invalidate on such a
+ * change even when schema text is unchanged.
+ */
+export const PROFILE_SEMANTIC_PAIR = {
+  schemaText: '{"type":"object","properties":{"files":{"type":"array"}}}',
+  first: { operation: 'publish', limits: { maxFiles: 32, maxTotalBytes: 262144 }, defaults: {} },
+  second: { operation: 'publish', limits: { maxFiles: 16, maxTotalBytes: 262144 }, defaults: {} },
+} as const;
+
+const isKnownToolName = (value: string): boolean =>
+  (KNOWN_ARTIFACT_TOOL_NAMES as readonly string[]).includes(value);
+
+/** Validate an explicit selection: reject unknown and duplicate entries. */
+export function validateToolSelection(selection: ToolSelection): string[] {
+  const errors: string[] = [];
+  if (!Array.isArray(selection.tools)) return ['selection tools must be an array'];
+  const seen = new Set<string>();
+  for (const tool of selection.tools) {
+    if (typeof tool !== 'string' || !isKnownToolName(tool)) {
+      errors.push(`unknown capability: ${String(tool)}`);
+      continue;
+    }
+    if (seen.has(tool)) errors.push(`duplicate capability: ${tool}`);
+    seen.add(tool);
+  }
+  return errors;
+}
+
+/** Binding names are required strings of 1-128 UTF-16 code units, unnormalized. */
+export function validateBindingName(value: unknown): boolean {
+  return typeof value === 'string' && value.length >= 1 && value.length <= 128;
+}
+
+/**
+ * Caller idempotency keys: original string, trim() must be nonempty,
+ * at most 256 UTF-16 code units. Whitespace around a nonempty value is
+ * retained; no trimming or Unicode normalization is applied. Lone high
+ * or low surrogates are rejected before UTF-8 conversion, derivation or
+ * storage so distinct caller keys can never alias one durable identity
+ * through replacement-character encoding.
+ */
+export function validateCallerIdempotencyKey(value: unknown): boolean {
+  if (typeof value !== 'string') return false;
+  if (value.length > 256 || value.trim().length === 0) return false;
+  for (let i = 0; i < value.length; i++) {
+    const unit = value.charCodeAt(i);
+    if (unit < 0xd800 || unit > 0xdfff) continue;
+    if (unit > 0xdbff) return false;
+    const next = i + 1 < value.length ? value.charCodeAt(i + 1) : 0;
+    if (next < 0xdc00 || next > 0xdfff) return false;
+    i++;
+  }
+  return true;
+}
+
+/** Radar publication files carry 1-32 entries within the decoded-byte budget. */
+export function validatePublishFileCount(count: unknown): boolean {
+  return typeof count === 'number' && Number.isInteger(count) && count >= 1 && count <= 32;
+}
+
+/** List bounds: integer limit 1-100, nonnegative integer offset. */
+export function validateListBounds(limit: unknown, offset: unknown): boolean {
+  return (
+    typeof limit === 'number' && Number.isInteger(limit) && limit >= 1 && limit <= 100 &&
+    typeof offset === 'number' && Number.isInteger(offset) && offset >= 0
+  );
+}

package/migrations/0003_coordinator.sql

@@ -0,0 +1,28 @@
+-- L3 (immo #861) — atomic finalization coordination (spec r2 §3.1 A4).
+--
+-- Additive only: no ALTER/DROP of existing objects. Two coordinator-owned
+-- tables. artifacts.operation_keys is the per-key serialization row keyed by
+-- (storage_scope_id, internal_key); it carries no success or authorization
+-- assertion. artifacts.operation_receipts holds exactly one success row per
+-- (storage_scope_id, internal_key) with the command codec, command hash and
+-- receipt; the primary key is the uniqueness fence. This migration is
+-- distinct from artifacts.idempotency_keys, whose success-row count MUST
+-- stay unchanged after a denial. The host applies this file through its
+-- existing journal after 0002_lifecycle.sql.
+
+CREATE TABLE IF NOT EXISTS artifacts.operation_keys (
+  storage_scope_id TEXT NOT NULL,
+  internal_key TEXT NOT NULL,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  PRIMARY KEY (storage_scope_id, internal_key)
+);
+
+CREATE TABLE IF NOT EXISTS artifacts.operation_receipts (
+  storage_scope_id TEXT NOT NULL,
+  internal_key TEXT NOT NULL,
+  command_codec TEXT NOT NULL,
+  command_hash TEXT NOT NULL,
+  receipt JSONB NOT NULL,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  PRIMARY KEY (storage_scope_id, internal_key)
+);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sentropic/artifacts",
-  "version": "0.1.4",
+  "version": "0.2.1",
   "description": "Generic configurable artifacts MCP and artifact service: StorageScope/Artifact/Binding/Release model, canonical manifests, object authorization, idempotent intents (spec-v8 §9).",
   "type": "module",
   "license": "MIT",
@@ -11,6 +11,11 @@
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "imports": {
+    "#artifacts-frozen-commit": {
+      "types": "./l0-freeze/commit-contract.ts"
+    }
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -32,6 +37,10 @@
       "types": "./dist/adapters/postgres.d.ts",
       "import": "./dist/adapters/postgres.js"
     },
+    "./adapters/postgres-commit": {
+      "types": "./dist/adapters/postgres-commit.d.ts",
+      "import": "./dist/adapters/postgres-commit.js"
+    },
     "./migrations/*": "./migrations/*",
     "./server/ports": {
       "types": "./dist/server/ports.d.ts",
@@ -45,6 +54,18 @@
       "types": "./dist/server/authorization.d.ts",
       "import": "./dist/server/authorization.js"
     },
+    "./server/commit-contract": {
+      "types": "./dist/server/commit-contract.d.ts",
+      "import": "./dist/server/commit-contract.js"
+    },
+    "./server/outcome-contract": {
+      "types": "./dist/server/outcome-contract.d.ts",
+      "import": "./dist/server/outcome-contract.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js"
+    },
     "./server/bindings": {
       "types": "./dist/server/bindings.d.ts",
       "import": "./dist/server/bindings.js"
@@ -144,7 +165,11 @@
   },
   "files": [
     "dist",
+    "l0-freeze",
+    "src/contracts.ts",
     "migrations",
+    "docs/migration-l6.md",
+    "examples/radar-commit-setup.ts",
     "README.md",
     "LICENSE"
   ],
@@ -155,6 +180,7 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc --noEmit -p tsconfig.json",
+    "freeze-types": "tsc --noEmit --strict --skipLibCheck --target es2022 --module nodenext --moduleResolution nodenext --verbatimModuleSyntax l0-freeze/commit-contract.ts l0-freeze/failure-contract.ts l0-freeze/profile-contract.ts l0-freeze/command-identity-contract.ts",
     "test": "vitest run tests"
   },
   "peerDependencies": {

package/src/contracts.ts

@@ -0,0 +1,125 @@
+/**
+ * L-5a — artifact domain contracts (spec-v8 §9).
+ *
+ * Generic, host-independent state: StorageScope, Artifact, Binding, Release,
+ * File/BlobRef, Source, ACL, hostname reservation, Upload, BlobPin,
+ * ObjectIntent and operation idempotency. Schema types are independent of
+ * ORM rows; no server, driver or cluster-mesh imports; no eager storage
+ * connections or DDL on import. Identities are server-allocated UUIDs.
+ */
+
+export const ARTIFACT_SCHEMA_VERSIONS = ['artifacts/v1'] as const;
+
+export type ArtifactSchemaVersion = (typeof ARTIFACT_SCHEMA_VERSIONS)[number];
+
+/** Refuse unknown schema versions (fail-closed on version skew). */
+export function assertKnownSchemaVersion(version: unknown): asserts version is ArtifactSchemaVersion {
+  if (!ARTIFACT_SCHEMA_VERSIONS.includes(version as ArtifactSchemaVersion)) {
+    throw new Error(`unknown artifact schema version: ${String(version)}`);
+  }
+}
+
+const UUID_PATTERN =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+
+/** True for server-allocated UUID identities. */
+export function isArtifactId(value: unknown): value is string {
+  return typeof value === 'string' && UUID_PATTERN.test(value);
+}
+
+/** JSON value (undefined only as an absent property, never serialized). */
+export type JsonValue = string | number | boolean | null | JsonObject | JsonValue[];
+export interface JsonObject {
+  [key: string]: JsonValue | undefined;
+}
+/**
+ * Content-addressed manifest: canonical bytes + SHA-256 digest, versioned
+ * schema. `digest` is optional: construction precedes sealing, so working
+ * documents carry no digest and sealed documents must verify against it.
+ */
+export interface CanonicalManifest {
+  schemaVersion: string;
+  digest?: string;
+  [key: string]: unknown;
+}
+
+/** Allocate a server-side identity (UUID v4). */
+export function createArtifactId(): string {
+  return crypto.randomUUID();
+}
+
+/** Opaque storage scope isolating physical keys from org reindexing. */
+export interface StorageScope {
+  readonly storageScopeId: string;
+  readonly createdAt: string;
+}
+
+/** An artifact: one logical view across releases. */
+export interface Artifact {
+  readonly id: string;
+  readonly schemaVersion: ArtifactSchemaVersion;
+  readonly storageScopeId: string;
+  readonly ownerId: string;
+  readonly createdAt: string;
+  readonly deletedAt?: string;
+}
+
+/** A stable owner-scoped binding resolving to one artifact. */
+export interface Binding {
+  readonly binding: string;
+  readonly artifactId: string;
+  readonly ownerId: string;
+}
+
+/** An immutable release of an artifact's manifest + bytes. */
+export interface Release {
+  readonly id: string;
+  readonly artifactId: string;
+  readonly manifestDigest: string;
+  readonly createdAt: string;
+  readonly state: 'pending' | 'ready' | 'withdrawn' | 'purged';
+}
+
+/** A content blob referenced by digest. */
+export interface BlobRef {
+  readonly digest: string;
+  readonly size: number;
+  readonly mimeType: string;
+}
+
+/** Provenance of a release's sources. */
+export type ArtifactSource =
+  | { readonly kind: 'inline-original' }
+  | { readonly kind: 'recipe'; readonly baseCommit: string; readonly recipe: string };
+
+/** Object-level access grant. */
+export interface AccessGrant {
+  readonly artifactId: string;
+  readonly subjectId: string;
+  readonly rights: readonly ('read' | 'source-export' | 'write')[];
+}
+
+/** A bounded upload session staging bytes before commit. */
+export interface Upload {
+  readonly id: string;
+  readonly artifactId: string;
+  readonly prefix: string;
+  readonly createdAt: string;
+  readonly state: 'open' | 'committed' | 'aborted';
+}
+
+/** A pin retaining a blob against concurrent GC. */
+export interface BlobPin {
+  readonly digest: string;
+  readonly artifactId: string;
+  readonly reason: 'release' | 'fork' | 'upload';
+}
+
+/** Recorded intent before every external object operation. */
+export interface ObjectIntent {
+  readonly idempotencyKey: string;
+  readonly artifactId: string;
+  readonly operation: string;
+  readonly recordedAt: string;
+  readonly state: 'recorded' | 'applied' | 'failed';
+}