@sentropic/artifacts 0.1.4 → 0.2.1

package/examples/radar-commit-setup.ts

@@ -0,0 +1,302 @@
+/**
+ * L3 (immo #861) — typed Radar construction example (conductor-directed).
+ *
+ * Shows the exact construction Radar wires: a real coordinator over the
+ * PostgreSQL executor, a transaction-bound PG policy/quota participant
+ * registered at construction, fence minting in the host guard, and the
+ * preparation-abandonment queue bound to a cleanup sweeper. Imports only
+ * public package entrypoints. Pass this coordinator plus the compiled profile to
+ * `createHttpArtifactApp` (r2 section 3.2); nothing here invents that seam.
+ * The `radar_commit_example` tables below are illustrative host tables so
+ * the example runs standalone; Radar's real adapter owns its own tables.
+ */
+import type { Pool } from 'pg';
+import { createPostgresCommitExecutor } from '@sentropic/artifacts/adapters/postgres-commit';
+import { createArtifactCommitCoordinator } from '@sentropic/artifacts/server/commit-contract';
+import { compileArtifactsProfile, RADAR_ARTIFACTS_PROFILE } from '@sentropic/artifacts/mcp-core';
+import { createPostgresArtifactStore } from '@sentropic/artifacts/adapters/postgres';
+import { createPostgresDeletionClaimStore } from '@sentropic/artifacts/server/gc';
+import { scheduleBoundedPreparationCleanup } from '@sentropic/artifacts/server/object-intents';
+import type { PublicationBlobStore } from '@sentropic/artifacts/server/publication';
+import type {
+  ArtifactAuthorizationDecision,
+  ArtifactCommitContext,
+  ArtifactCommitTransaction,
+  ArtifactPolicyDriver,
+  CommitPolicyParticipantFactory,
+  CommitCoordinatorOptions,
+  CoordinatorTestPoint,
+  ArtifactCommitCoordinator,
+  FinalizeRequest,
+  FinalizeResult,
+  InternalIdempotencyKey,
+} from '@sentropic/artifacts/server/commit-contract';
+
+/** One abandoned preparation awaiting host cleanup. */
+export interface AbandonedAttempt {
+  readonly attemptId: string;
+  readonly scopeId: string;
+  readonly internalKey: string;
+  readonly atMs: number;
+}
+
+/** Configure publication with this lifetime; sweep cadence is part of the activation bound. */
+export const RADAR_PREPARATION_LIFETIME_MS = 30_000;
+
+/** Bind durable intent cleanup before activation; observe failures as preparation debt. */
+export function startRadarPreparationCleanup(options: {
+  pool: Pool;
+  blobs: PublicationBlobStore;
+  onError(error: unknown): void;
+  intervalMs?: number;
+}): { runOnce(): Promise<void>; stop(): void } {
+  const intervalMs = options.intervalMs ?? 1000;
+  if (!Number.isSafeInteger(intervalMs) || intervalMs < 1 || intervalMs > RADAR_PREPARATION_LIFETIME_MS) {
+    throw new Error('invalid preparation cleanup interval');
+  }
+  const executor = createPostgresCommitExecutor(options.pool);
+  const store = createPostgresArtifactStore(options.pool);
+  let running: Promise<void> | undefined;
+  const runOnce = (): Promise<void> => {
+    if (running !== undefined) return running;
+    running = (async () => {
+      const client = await executor.beginFinalization();
+      let failure: unknown;
+      try {
+        await client.beginReadCommitted();
+        await scheduleBoundedPreparationCleanup({ intents: store, refs: store,
+          claims: createPostgresDeletionClaimStore(client), blobs: options.blobs }, Date.now());
+        await client.commit();
+      } catch (error) {
+        failure = error;
+        try { await client.rollback(); } catch (rollbackError) { failure = rollbackError; }
+        throw error;
+      } finally { client.release(failure); }
+    })().finally(() => { running = undefined; });
+    return running;
+  };
+  const timer = setInterval(() => { void runOnce().catch(options.onError); }, intervalMs);
+  return { runOnce, stop: () => clearInterval(timer) };
+}
+
+/** Create the illustrative host tables and seed one approved actor plus quota. */
+export async function prepareRadarCommitExample(pool: Pool): Promise<void> {
+  await pool.query('CREATE SCHEMA IF NOT EXISTS radar_commit_example');
+  await pool.query(
+    `CREATE TABLE IF NOT EXISTS radar_commit_example.policy_revision
+       (id INT PRIMARY KEY CHECK (id = 1), revision TEXT NOT NULL)`,
+  );
+  await pool.query(
+    `INSERT INTO radar_commit_example.policy_revision (id, revision)
+     VALUES (1, 'rev-1') ON CONFLICT (id) DO UPDATE SET revision = 'rev-1'`,
+  );
+  await pool.query(
+    `CREATE TABLE IF NOT EXISTS radar_commit_example.approvals
+       (actor_id TEXT PRIMARY KEY, approved BOOLEAN NOT NULL, expires_at_ms BIGINT NOT NULL)`,
+  );
+  await pool.query(
+    `INSERT INTO radar_commit_example.approvals (actor_id, approved, expires_at_ms)
+     VALUES ('radar-actor', true, 9999999999999)
+     ON CONFLICT (actor_id) DO UPDATE SET approved = true, expires_at_ms = 9999999999999`,
+  );
+  await pool.query(
+    `CREATE TABLE IF NOT EXISTS radar_commit_example.quotas
+       (quota_key TEXT PRIMARY KEY, total INT NOT NULL, used INT NOT NULL)`,
+  );
+  await pool.query(
+    `INSERT INTO radar_commit_example.quotas (quota_key, total, used)
+     VALUES ('radar-quota', 100, 0) ON CONFLICT (quota_key) DO UPDATE SET used = 0`,
+  );
+}
+
+/** The host guard Radar wires: current revision, approval and fence minting. */
+export async function allowRadarGuard(
+  context: ArtifactCommitContext,
+  transaction: ArtifactCommitTransaction,
+): Promise<ArtifactAuthorizationDecision> {
+  const revision = await transaction.participant.readRevision();
+  if (context.policyRevision !== revision) {
+    return {
+      allowed: false, reason: 'revoked', publicCode: 'access_denied', status: 403, retriable: false,
+    };
+  }
+  const check = await transaction.participant.checkApproval({
+    actorId: context.actorId,
+    operation: context.operation,
+  });
+  if (!check.approved) {
+    return {
+      allowed: false, reason: check.reason ?? 'denied',
+      publicCode: 'access_denied', status: 403, retriable: false,
+    };
+  }
+  return { allowed: true, fence: transaction.participant.mintFence(revision, context.invocationId) };
+}
+
+const createParticipantFactory = (
+  quotaKey: string,
+  clock: { nowMs: number },
+): CommitPolicyParticipantFactory => ({
+  createParticipant: (client, transactionToken): ArtifactPolicyDriver => ({
+    async readRevision(): Promise<string> {
+      const { rows } = await client.query<{ revision: string }>(
+        'SELECT revision FROM radar_commit_example.policy_revision WHERE id = 1 FOR SHARE',
+        [],
+      );
+      const row = rows[0];
+      if (row === undefined) throw new Error('missing policy revision');
+      return row.revision;
+    },
+    async checkApproval(input: { actorId: string }) {
+      const { rows } = await client.query<{ approved: boolean; expires_at_ms: string }>(
+        'SELECT approved, expires_at_ms FROM radar_commit_example.approvals WHERE actor_id = $1 FOR SHARE',
+        [input.actorId],
+      );
+      const row = rows[0];
+      if (row === undefined || !row.approved) return { approved: false as const, reason: 'denied' as const };
+      if (Number(row.expires_at_ms) <= clock.nowMs) {
+        return { approved: false as const, reason: 'expired' as const };
+      }
+      return { approved: true as const };
+    },
+    async reserveQuota(): Promise<{ reserved: boolean }> {
+      const { rowCount } = await client.query(
+        'UPDATE radar_commit_example.quotas SET used = used + 1 WHERE quota_key = $1 AND used < total',
+        [quotaKey],
+      );
+      return { reserved: rowCount > 0 };
+    },
+    mintFence: (revision: string, invocationId: string) => ({
+      fenceId: `fence-${transactionToken}`,
+      transactionId: transactionToken,
+      invocationId,
+      policyRevision: revision,
+    }),
+  }),
+});
+
+export interface RadarCommitInput {
+  readonly scopeId: string;
+  readonly internalKey: string;
+  readonly commandHash: string;
+  readonly invocationId: string;
+  readonly operation: string;
+  readonly receiptData: unknown;
+}
+
+export interface RadarCommitSetup {
+  readonly coordinator: ArtifactCommitCoordinator;
+  readonly profile: ReturnType<typeof compileArtifactsProfile>;
+  readonly abandonedAttempts: AbandonedAttempt[];
+  finalizePrepared(input: RadarCommitInput): Promise<FinalizeResult>;
+  replayPrepared(input: RadarCommitInput): Promise<FinalizeResult>;
+  drainAbandonedAttempts(onSweep: (batch: AbandonedAttempt[]) => void): void;
+  startAbandonedAttemptSweep(
+    onSweep: (batch: AbandonedAttempt[]) => void | Promise<void>,
+    intervalMs: number,
+  ): () => void;
+}
+
+/**
+ * Build the exact Radar construction over one pool. The optional
+ * `testObserver` forwards barrier observations to the coordinator;
+ * `testPoints` optionally filters them (see `testing.ts`).
+ */
+export function createRadarCommitSetup(options: {
+  pool: Pool;
+  clock: { nowMs: number };
+  quotaKey?: string;
+  /** Bind this same mapper on createHttpArtifactApp and createArtifactsAdapter. */
+  mapHostError?: CommitCoordinatorOptions['mapHostError'];
+  testObserver?: CommitCoordinatorOptions['testObserver'];
+  testPoints?: readonly CoordinatorTestPoint[];
+}): RadarCommitSetup {
+  const quotaKey = options.quotaKey ?? 'radar-quota';
+  const abandonedAttempts: AbandonedAttempt[] = [];
+  const coordinator = createArtifactCommitCoordinator({
+    mapHostError: options.mapHostError,
+    executor: createPostgresCommitExecutor(options.pool),
+    policy: createParticipantFactory(quotaKey, options.clock),
+    nowMs: () => options.clock.nowMs,
+    testObserver: options.testObserver,
+    testPoints: options.testPoints,
+  });
+  const toRequest = (
+    input: RadarCommitInput,
+  ): FinalizeRequest & { attemptId: string } => ({
+    scopeId: input.scopeId,
+    internalKey: input.internalKey as InternalIdempotencyKey,
+    commandHash: input.commandHash,
+    codecVersion: 'artifacts-command/v1',
+    invocationId: input.invocationId,
+    actorId: 'radar-actor',
+    operation: input.operation,
+    artifactId: null,
+    bindingName: null,
+    policyRevision: 'rev-1',
+    guard: allowRadarGuard,
+    receiptData: input.receiptData,
+    attemptId: input.invocationId,
+    noteAbandonedAttempt: async (attemptId: string) => {
+      abandonedAttempts.push({
+        attemptId,
+        scopeId: input.scopeId,
+        internalKey: input.internalKey,
+        atMs: options.clock.nowMs,
+      });
+    },
+  });
+  const drainAbandonedAttempts = (onSweep: (batch: AbandonedAttempt[]) => void): void => {
+    if (abandonedAttempts.length === 0) return;
+    // Retain-then-remove: a throwing sweeper keeps the batch for the next
+    // sweep instead of losing it. Durable cleanup state, per-attempt
+    // deadlines and restart recovery stay L4-owned (intent metadata).
+    const batch = abandonedAttempts.slice();
+    onSweep(batch);
+    abandonedAttempts.splice(0, batch.length);
+  };
+  return {
+    coordinator,
+    profile: compileArtifactsProfile(RADAR_ARTIFACTS_PROFILE),
+    abandonedAttempts,
+    finalizePrepared: (input: RadarCommitInput) => coordinator.finalizePrepared(toRequest(input)),
+    replayPrepared: (input: RadarCommitInput) => coordinator.replayPrepared(toRequest(input)),
+    drainAbandonedAttempts,
+    startAbandonedAttemptSweep: (onSweep, intervalMs) => {
+      // Serialized sweeps: an overlapping tick queues behind the running
+      // sweep instead of sweeping concurrently, and only the swept entries
+      // are removed, so arrivals landing mid-sweep are never deleted.
+      let sweeping = false;
+      let queued = false;
+      const runSweep = (): void => {
+        if (sweeping) {
+          queued = true;
+          return;
+        }
+        sweeping = true;
+        void (async () => {
+          try {
+            do {
+              queued = false;
+              const batch = abandonedAttempts.slice();
+              try {
+                await onSweep(batch);
+              } catch {
+                /* retained for the next sweep */
+                break;
+              }
+              for (const entry of batch) {
+                const index = abandonedAttempts.indexOf(entry);
+                if (index !== -1) abandonedAttempts.splice(index, 1);
+              }
+            } while (queued);
+          } finally {
+            sweeping = false;
+          }
+        })();
+      };
+      const timer = setInterval(runSweep, intervalMs);
+      return () => clearInterval(timer);
+    },
+  };
+}

package/l0-freeze/command-identity-contract.ts

@@ -0,0 +1,303 @@
+/**
+ * L0 frozen command-identity declaration (immo #861, ask 1 shape, spec r2 C5-C7).
+ *
+ * Stable data shapes for the effective command and its server-created
+ * identity, plus the frozen derivation fixtures: preimage construction,
+ * expected digests and ambiguous-split refusal. The command codec
+ * implementation lands in L1/L6 against the declared relations; domain
+ * qualification of trusted scope/subject mappings stays gated on Q0.
+ */
+
+/** Version of the frozen command-codec shape. */
+export const COMMAND_CODEC_VERSION = 'artifacts-command/v1' as const;
+
+/** Caller-supplied key: opaque to the server, never trusted as identity. */
+export type CallerIdempotencyKey = string & { readonly __brand: 'caller-key' };
+
+/** Server-derived internal key: distinct from any caller key. */
+export type InternalIdempotencyKey = string & { readonly __brand: 'internal-key' };
+
+/**
+ * Trusted host derivation binding. The algorithm names Radar's existing
+ * SHA-256 construction over the UTF-8 encoding of the five components
+ * joined with `|`, in scope/actor/operation/objectId/callerKey order.
+ * An ambiguous concatenation MUST fail host configuration or use an
+ * explicitly versioned migration; existing durable keys are never
+ * silently re-derived.
+ */
+export interface IdempotencyDerivationBinding {
+  readonly algorithm: 'radar-derive-idempotency-v1';
+  readonly scope: string;
+  readonly actor: string;
+  readonly operation: string;
+  readonly objectId: string;
+  readonly callerKey: string;
+}
+
+/** Join the five binding components with `|`; the hash covers this preimage. */
+export function buildDerivationPreimage(binding: IdempotencyDerivationBinding): string {
+  return [
+    binding.scope, binding.actor, binding.operation,
+    binding.objectId, binding.callerKey,
+  ].join('|');
+}
+
+/** One expected derivation fixture with its precomputed SHA-256 digest. */
+export interface DerivationVector {
+  readonly name: string;
+  readonly binding: IdempotencyDerivationBinding;
+  readonly preimage: string;
+  readonly sha256: string;
+}
+
+export const DERIVATION_VECTORS: readonly DerivationVector[] = [
+  {
+    name: 'publish-basic',
+    binding: {
+      algorithm: 'radar-derive-idempotency-v1', scope: 's', actor: 'alice',
+      operation: 'publish', objectId: 'obj-1', callerKey: 'key-1',
+    },
+    preimage: 's|alice|publish|obj-1|key-1',
+    sha256: '4a7c17265a6ee4720ff3e941bc42f9c3f2f55b64094076b591d5484d698c7d6a',
+  },
+  {
+    name: 'ambiguous-split-preimage',
+    binding: {
+      algorithm: 'radar-derive-idempotency-v1', scope: 's|issuer', actor: 'alice',
+      operation: 'publish', objectId: 'obj-1', callerKey: 'key-1',
+    },
+    preimage: 's|issuer|alice|publish|obj-1|key-1',
+    sha256: '535a79665cbecdcd2c20621d05791568f3f57bacc76b5f059b91f6d0ceda4bb2',
+  },
+  {
+    name: 'ensure-empty-object',
+    binding: {
+      algorithm: 'radar-derive-idempotency-v1', scope: 'tenant:t1', actor: 'alice',
+      operation: 'ensure', objectId: '', callerKey: 'key-2',
+    },
+    preimage: 'tenant:t1|alice|ensure||key-2',
+    sha256: '437be4b21dce49e880ba3cc697fef667bed4ed0c0ec90e9cbdbad43f1a4a5cbb',
+  },
+  {
+    name: 'ensure-alice',
+    binding: {
+      algorithm: 'radar-derive-idempotency-v1', scope: 's', actor: 'alice',
+      operation: 'ensure', objectId: '', callerKey: 'key-2',
+    },
+    preimage: 's|alice|ensure||key-2',
+    sha256: '68934203b875d8ea78a6533b2a971f86b49c1c32416da4af8bd786058a49e1fa',
+  },
+  {
+    name: 'ensure-issuer-alice',
+    binding: {
+      algorithm: 'radar-derive-idempotency-v1', scope: 's', actor: 'issuer|alice',
+      operation: 'ensure', objectId: '', callerKey: 'key-2',
+    },
+    preimage: 's|issuer|alice|ensure||key-2',
+    sha256: '1d9b9a3f67238ad0cc6a7ac257232c2d0a1e5dc709d58d09901a2ca68fb98b28',
+  },
+];
+
+/**
+ * True when two bindings share one preimage through different component
+ * splits. Such an ambiguous concatenation is refused: the distinct
+ * scope/actor pairs never share a durable identity without an explicitly
+ * qualified canonical mapping or a versioned migration.
+ */
+export function detectAmbiguousSplit(
+  first: IdempotencyDerivationBinding,
+  second: IdempotencyDerivationBinding,
+): boolean {
+  if (buildDerivationPreimage(first) !== buildDerivationPreimage(second)) return false;
+  return first.scope !== second.scope
+    || first.actor !== second.actor
+    || first.operation !== second.operation
+    || first.objectId !== second.objectId
+    || first.callerKey !== second.callerKey;
+}
+
+/**
+ * C7 negative fixture: `('s|issuer', 'alice')` and `('s', 'issuer|alice')`
+ * produce the same legacy preimage with identical remaining components,
+ * so the host MUST refuse (or versioned-migrate) before acceptance. HTTP
+ * `alice` versus MCP `issuer|alice` without a qualified canonical mapping
+ * are likewise distinct principals and MUST NOT replay each other's receipt.
+ */
+export const AMBIGUOUS_DERIVATION_CASE = {
+  first: {
+    algorithm: 'radar-derive-idempotency-v1', scope: 's|issuer', actor: 'alice',
+    operation: 'publish', objectId: 'obj-1', callerKey: 'key-1',
+  },
+  second: {
+    algorithm: 'radar-derive-idempotency-v1', scope: 's', actor: 'issuer|alice',
+    operation: 'publish', objectId: 'obj-1', callerKey: 'key-1',
+  },
+  expected: 'refuse',
+} as const;
+
+/**
+ * Platform envelope rule (C7): the optional envelope key is never an
+ * alternative source. `accept` proceeds, `conflict` is a 400 on a
+ * mismatching envelope, `envelope-only` is a 400 on an envelope without
+ * a tool argument. It adds no second platform idempotency store.
+ */
+export function resolvePlatformEnvelope(
+  argumentKey: string | undefined,
+  envelopeKey: string | undefined,
+): 'accept' | 'conflict' | 'envelope-only' {
+  if (argumentKey === undefined) return 'envelope-only';
+  if (envelopeKey === undefined || envelopeKey === argumentKey) return 'accept';
+  return 'conflict';
+}
+
+/**
+ * Command-identity relations the L1/L6 codec MUST enforce: equivalent
+ * text/byte inputs and object-property order converge, while changed
+ * bytes, path, MIME, profile, provenance or file-array order conflict
+ * under the same internal key. A hash supplied in a public request never
+ * overrides the computed hash.
+ */
+export const COMMAND_IDENTITY_RELATIONS = [
+  {
+    name: 'text-bytes-equivalence',
+    description: 'Equivalent text and byte file inputs converge to one command hash.',
+    expectation: 'converge',
+  },
+  {
+    name: 'file-array-order',
+    description: 'Changed file-array order conflicts under the same internal key.',
+    expectation: 'conflict',
+  },
+  {
+    name: 'request-hash-ignored',
+    description: 'A hash supplied in a public request never overrides the computed hash.',
+    expectation: 'computed-only',
+  },
+] as const;
+
+/**
+ * Deterministic JSON canonicalization for effective command bodies:
+ * object keys sort recursively in UTF-16 code-unit order, array order
+ * stays significant, and the encoder never mutates its input. L1/L6 hash
+ * the canonical bytes (SHA-256) after trusted scope binding, defaults,
+ * UTF-8/byte conversion and forced provenance; text/byte equivalence is
+ * established on the decoded form before this encoding, and the codec
+ * deep-copies before normalization.
+ */
+export function canonicalizeJson(value: unknown): string {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value) ?? 'null';
+  if (Array.isArray(value)) {
+    return `[${value.map((entry) => canonicalizeJson(entry)).join(',')}]`;
+  }
+  const record = value as Record<string, unknown>;
+  const keys = Object.keys(record).sort();
+  return `{${keys.map((key) => `${JSON.stringify(key)}:${canonicalizeJson(record[key])}`).join(',')}}`;
+}
+
+/** One golden effective-command fixture with its canonical bytes and digest. */
+export interface CanonicalCommandFixture {
+  readonly name: string;
+  readonly body: {
+    readonly operation: string;
+    readonly scopeBinding: string;
+    readonly payload: Record<string, unknown>;
+  };
+  readonly canonical: string;
+  readonly sha256: string;
+}
+
+export const CANONICAL_COMMAND_FIXTURES: readonly CanonicalCommandFixture[] = [
+  {
+    name: 'publish-baseline',
+    body: {
+      operation: 'publish',
+      scopeBinding: 's',
+      payload: {
+        artifactId: 'obj-1',
+        files: [
+          { bytes: [60, 104, 49, 62, 72, 105, 60, 47, 104, 49, 62], mimeType: 'text/html', path: 'index.html' },
+          { bytes: [98, 111, 100, 121], mimeType: 'text/css', path: 'styles.css' },
+        ],
+        profile: {},
+        provenance: { kind: 'inline-original' },
+      },
+    },
+    canonical: '{"operation":"publish","payload":{"artifactId":"obj-1","files":[{"bytes":[60,104,49,62,72,105,60,47,104,49,62],"mimeType":"text/html","path":"index.html"},{"bytes":[98,111,100,121],"mimeType":"text/css","path":"styles.css"}],"profile":{},"provenance":{"kind":"inline-original"}},"scopeBinding":"s"}',
+    sha256: 'c1c8a186b847635ae4b1d1c27bf1079ae1cf26c1ef4b47ed622cafaa6a273d57',
+  },
+  {
+    name: 'publish-shuffled-keys',
+    body: {
+      payload: {
+        provenance: { kind: 'inline-original' },
+        profile: {},
+        files: [
+          { path: 'index.html', mimeType: 'text/html', bytes: [60, 104, 49, 62, 72, 105, 60, 47, 104, 49, 62] },
+          { path: 'styles.css', mimeType: 'text/css', bytes: [98, 111, 100, 121] },
+        ],
+        artifactId: 'obj-1',
+      },
+      scopeBinding: 's',
+      operation: 'publish',
+    },
+    canonical: '{"operation":"publish","payload":{"artifactId":"obj-1","files":[{"bytes":[60,104,49,62,72,105,60,47,104,49,62],"mimeType":"text/html","path":"index.html"},{"bytes":[98,111,100,121],"mimeType":"text/css","path":"styles.css"}],"profile":{},"provenance":{"kind":"inline-original"}},"scopeBinding":"s"}',
+    sha256: 'c1c8a186b847635ae4b1d1c27bf1079ae1cf26c1ef4b47ed622cafaa6a273d57',
+  },
+  {
+    name: 'publish-swapped-file-order',
+    body: {
+      operation: 'publish',
+      scopeBinding: 's',
+      payload: {
+        artifactId: 'obj-1',
+        files: [
+          { bytes: [98, 111, 100, 121], mimeType: 'text/css', path: 'styles.css' },
+          { bytes: [60, 104, 49, 62, 72, 105, 60, 47, 104, 49, 62], mimeType: 'text/html', path: 'index.html' },
+        ],
+        profile: {},
+        provenance: { kind: 'inline-original' },
+      },
+    },
+    canonical: '{"operation":"publish","payload":{"artifactId":"obj-1","files":[{"bytes":[98,111,100,121],"mimeType":"text/css","path":"styles.css"},{"bytes":[60,104,49,62,72,105,60,47,104,49,62],"mimeType":"text/html","path":"index.html"}],"profile":{},"provenance":{"kind":"inline-original"}},"scopeBinding":"s"}',
+    sha256: 'ebf2c9342f120f4aeea857656cce1ff91a359d16eb493af97878350bc7b0f990',
+  },
+  {
+    name: 'publish-changed-mime',
+    body: {
+      operation: 'publish',
+      scopeBinding: 's',
+      payload: {
+        artifactId: 'obj-1',
+        files: [
+          { bytes: [60, 104, 49, 62, 72, 105, 60, 47, 104, 49, 62], mimeType: 'text/html', path: 'index.html' },
+          { bytes: [98, 111, 100, 121], mimeType: 'text/javascript', path: 'styles.css' },
+        ],
+        profile: {},
+        provenance: { kind: 'inline-original' },
+      },
+    },
+    canonical: '{"operation":"publish","payload":{"artifactId":"obj-1","files":[{"bytes":[60,104,49,62,72,105,60,47,104,49,62],"mimeType":"text/html","path":"index.html"},{"bytes":[98,111,100,121],"mimeType":"text/javascript","path":"styles.css"}],"profile":{},"provenance":{"kind":"inline-original"}},"scopeBinding":"s"}',
+    sha256: '90d3680386f461353f16f2c004271b1298a67895b3249eec1566320a52990528',
+  },
+];
+
+/** Server-created identity for one durable command. */
+export interface CommandIdentity {
+  readonly internalKey: InternalIdempotencyKey;
+  readonly commandHash: string;
+  readonly codecVersion: typeof COMMAND_CODEC_VERSION;
+}
+
+/**
+ * Effective command after trusted scope binding, defaults, UTF-8/byte
+ * conversion and forced provenance. Object keys sort recursively; array
+ * order remains significant. A hash supplied in a public request never
+ * overrides the computed hash.
+ */
+export interface EffectiveArtifactCommand {
+  readonly operation: string;
+  readonly scopeBinding: string;
+  readonly payload: Record<string, unknown>;
+  readonly provenance: { readonly kind: 'inline-original' };
+  readonly identity: CommandIdentity;
+}