promote: dev history slice 2 of 4

docs/release-evidence/sa-spreadsheet-auditor-slice.md

@@ -0,0 +1,41 @@
+# Spreadsheet Auditor vertical-slice evidence
+
+This record describes the implemented checkpoint on the Spreadsheet Auditor plan. It is
+deliberately marked **partial**: it does not release SA-001..SA-027 or replace the full
+module gate in `docs/plans/110-spreadsheet-auditor.md`.
+
+## Included in this checkpoint
+
+- Safe deterministic XLSX inventory and formula-family anomaly detection in
+  `services/engine/src/databreeze_engine/processors/spreadsheet_auditor.py`.
+- A Python manifest bridge that adds server-issued opaque identities and tenant scope without
+  copying workbook values in
+  `services/engine/src/databreeze_engine/processors/spreadsheet_auditor_manifest.py`.
+- The canonical value-free TypeScript result contract in
+  `packages/domain/src/spreadsheet-audit/v1.ts`.
+- Tenant-scoped API registration, lookup, and artifact-version listing under
+  `/v1/spreadsheet-audits`.
+- Immutable in-memory and Prisma adapters with the `sa` PostgreSQL schema and migration.
+- Unknown-field rejection tests proving formulas, source values, and raw rows cannot enter the
+  HTTP result boundary.
+
+## Evidence collected
+
+- Domain build, public API smoke test, and domain test suite pass.
+- API typecheck, API test compilation, targeted API controller/adapter tests, OpenAPI generation,
+  Prisma validation/generation, and migration inventory checks pass.
+- Python sources and tests pass `python -m py_compile`.
+
+The Python `uv` test command remains blocked by the existing Windows engine environment: the
+checked-in `.venv\Scripts\python.exe` exits with `0xc0e90002` before pytest starts. Recreate or
+repair that environment in a dedicated follow-up task; do not mark the engine requirement
+verified from the compile-only result.
+
+## Safety and rollback
+
+- The parser rejects archive traversal, duplicate members, XML entity/DTD payloads, and resource
+  exhaustion; macros and external links are disclosed as blocked reasons and never executed.
+- Result persistence is immutable and tenant scoped. Replaying the same audit ID is idempotent;
+  conflicting content fails closed.
+- The slice is independently reversible through the commits on
+  `feat/artifacts-datasets-completion`; the next integration step is a reviewed PR to `dev`.

packages/domain/package.json

@@ -72,6 +72,22 @@
       "types": "./src/artifact-governance/v1.ts",
       "import": "./dist/artifact-governance/v1.js"
     },
+    "./artifact-retention/v1": {
+      "types": "./src/artifact-retention/v1.ts",
+      "import": "./dist/artifact-retention/v1.js"
+    },
+    "./artifact-export/v1": {
+      "types": "./src/artifact-export/v1.ts",
+      "import": "./dist/artifact-export/v1.js"
+    },
+    "./artifact-upload/v1": {
+      "types": "./src/artifact-upload/v1.ts",
+      "import": "./dist/artifact-upload/v1.js"
+    },
+    "./protected-document/v1": {
+      "types": "./src/protected-document/v1.ts",
+      "import": "./dist/protected-document/v1.js"
+    },
     "./dataset/v1": {
       "types": "./src/dataset/v1.ts",
       "import": "./dist/dataset/v1.js"
@@ -80,6 +96,22 @@
       "types": "./src/dataset-governance/v1.ts",
       "import": "./dist/dataset-governance/v1.js"
     },
+    "./dataset-quality/v1": {
+      "types": "./src/dataset-quality/v1.ts",
+      "import": "./dist/dataset-quality/v1.js"
+    },
+    "./dataset-profile/v1": {
+      "types": "./src/dataset-profile/v1.ts",
+      "import": "./dist/dataset-profile/v1.js"
+    },
+    "./dataset-export/v1": {
+      "types": "./src/dataset-export/v1.ts",
+      "import": "./dist/dataset-export/v1.js"
+    },
+    "./spreadsheet-audit/v1": {
+      "types": "./src/spreadsheet-audit/v1.ts",
+      "import": "./dist/spreadsheet-audit/v1.js"
+    },
     "./jobs/v1": {
       "types": "./src/jobs/v1.ts",
       "import": "./dist/jobs/v1.js"

packages/domain/src/artifact-export/v1.ts

@@ -0,0 +1,159 @@
+import {
+  parseStableIdentifierV1,
+  parseStrictUtcTimestampV1,
+  parseTenantScopeV1,
+  tenantScopesEqualV1,
+  type StableIdentifierV1,
+  type StrictUtcTimestampV1,
+  type TenantScopeV1,
+} from '../tenant-scope/v1.js';
+
+/** IAE-018: independent verification manifest for governed artifact exports. */
+export const ARTIFACT_EXPORT_SCHEMA_VERSION_V1 = 1 as const;
+
+export type ExportApprovalStateV1 = 'NOT_REQUIRED' | 'PENDING' | 'APPROVED' | 'REJECTED';
+
+export interface ArtifactExportEntryV1 {
+  readonly versionId: StableIdentifierV1;
+  readonly contentSha256: string;
+  readonly byteSize: number;
+  readonly evidenceIds: readonly StableIdentifierV1[];
+  readonly processorVersions: readonly string[];
+}
+
+export interface ArtifactExportManifestV1 {
+  readonly schemaVersion: typeof ARTIFACT_EXPORT_SCHEMA_VERSION_V1;
+  readonly manifestId: StableIdentifierV1;
+  readonly tenantScope: TenantScopeV1;
+  readonly entries: readonly ArtifactExportEntryV1[];
+  readonly approvalState: ExportApprovalStateV1;
+  readonly createdAt: StrictUtcTimestampV1;
+  readonly canonicalHash: string;
+}
+
+export type ArtifactExportErrorCodeV1 =
+  | 'INVALID_IDENTIFIER'
+  | 'INVALID_SCOPE'
+  | 'CROSS_SCOPE'
+  | 'INVALID_TIMESTAMP'
+  | 'INVALID_HASH'
+  | 'INVALID_ENTRY'
+  | 'DUPLICATE_IDENTIFIER'
+  | 'INVALID_APPROVAL';
+
+export type ArtifactExportResultV1<TValue> =
+  | { readonly accepted: true; readonly value: TValue }
+  | { readonly accepted: false; readonly code: ArtifactExportErrorCodeV1 };
+
+function accepted<TValue>(value: TValue): ArtifactExportResultV1<TValue> {
+  return Object.freeze({ accepted: true, value });
+}
+
+function rejected(code: ArtifactExportErrorCodeV1): ArtifactExportResultV1<never> {
+  return Object.freeze({ accepted: false, code });
+}
+
+function identifier(input: unknown): StableIdentifierV1 | undefined {
+  const result = parseStableIdentifierV1(input);
+  return result.accepted ? result.value : undefined;
+}
+
+function timestamp(input: unknown): StrictUtcTimestampV1 | undefined {
+  const result = parseStrictUtcTimestampV1(input);
+  return result.accepted ? result.value : undefined;
+}
+
+function text(input: unknown): string | undefined {
+  return typeof input === 'string' &&
+    input.length > 0 &&
+    input.length <= 128 &&
+    !/\p{Cc}/u.test(input)
+    ? input.normalize('NFC').trim()
+    : undefined;
+}
+
+export function createArtifactExportManifestV1(input: {
+  readonly manifestId: unknown;
+  readonly tenantScope: unknown;
+  readonly entries: unknown;
+  readonly approvalState: unknown;
+  readonly createdAt: unknown;
+  readonly canonicalHash: unknown;
+}): ArtifactExportResultV1<ArtifactExportManifestV1> {
+  const manifestId = identifier(input.manifestId);
+  const tenantScope = parseTenantScopeV1(input.tenantScope);
+  const createdAt = timestamp(input.createdAt);
+  const canonicalHash =
+    typeof input.canonicalHash === 'string' && /^[0-9a-f]{64}$/u.test(input.canonicalHash)
+      ? input.canonicalHash.toLowerCase()
+      : undefined;
+  if (!manifestId) return rejected('INVALID_IDENTIFIER');
+  if (!tenantScope.accepted) return rejected('INVALID_SCOPE');
+  if (!createdAt) return rejected('INVALID_TIMESTAMP');
+  if (!canonicalHash) return rejected('INVALID_HASH');
+  if (!['NOT_REQUIRED', 'PENDING', 'APPROVED', 'REJECTED'].includes(input.approvalState as string))
+    return rejected('INVALID_APPROVAL');
+  if (!Array.isArray(input.entries) || input.entries.length === 0 || input.entries.length > 1024)
+    return rejected('INVALID_ENTRY');
+  const entries: ArtifactExportEntryV1[] = [];
+  for (const candidate of input.entries) {
+    if (typeof candidate !== 'object' || candidate === null || Array.isArray(candidate))
+      return rejected('INVALID_ENTRY');
+    const record = candidate as Record<string, unknown>;
+    const versionId = identifier(record['versionId']);
+    const contentSha256 =
+      typeof record['contentSha256'] === 'string' && /^[0-9a-f]{64}$/u.test(record['contentSha256'])
+        ? record['contentSha256'].toLowerCase()
+        : undefined;
+    const byteSize = record['byteSize'];
+    const evidenceIds = Array.isArray(record['evidenceIds'])
+      ? record['evidenceIds'].map(identifier)
+      : undefined;
+    const processorVersions = Array.isArray(record['processorVersions'])
+      ? record['processorVersions'].map(text)
+      : undefined;
+    if (
+      !versionId ||
+      !contentSha256 ||
+      typeof byteSize !== 'number' ||
+      !Number.isSafeInteger(byteSize) ||
+      byteSize < 0 ||
+      !evidenceIds ||
+      evidenceIds.some((value): value is undefined => value === undefined) ||
+      !processorVersions ||
+      processorVersions.some((value): value is undefined => value === undefined)
+    )
+      return rejected('INVALID_ENTRY');
+    entries.push(
+      Object.freeze({
+        versionId,
+        contentSha256,
+        byteSize,
+        evidenceIds: Object.freeze(evidenceIds as StableIdentifierV1[]),
+        processorVersions: Object.freeze(processorVersions as string[]),
+      }),
+    );
+  }
+  if (new Set(entries.map((entry) => entry.versionId)).size !== entries.length)
+    return rejected('DUPLICATE_IDENTIFIER');
+  if (entries.some((entry) => entry.evidenceIds.some((evidenceId) => !evidenceId)))
+    return rejected('INVALID_ENTRY');
+  return accepted(
+    Object.freeze({
+      schemaVersion: ARTIFACT_EXPORT_SCHEMA_VERSION_V1,
+      manifestId,
+      tenantScope: tenantScope.value,
+      entries: Object.freeze(entries),
+      approvalState: input.approvalState as ExportApprovalStateV1,
+      createdAt,
+      canonicalHash,
+    }),
+  );
+}
+
+export function exportScopesEqualV1(
+  left: ArtifactExportManifestV1,
+  right: ArtifactExportManifestV1,
+): boolean {
+  return tenantScopesEqualV1(left.tenantScope, right.tenantScope);
+}

packages/domain/src/artifact-intake/v1.ts

@@ -21,6 +21,7 @@ export type InboxItemStateV1 =
   | 'QUARANTINED'
   | 'ARCHIVED';
 export type ArtifactScanStateV1 = 'PENDING' | 'CLEAN' | 'MALICIOUS' | 'FAILED';
+export type InboxPriorityV1 = 'LOW' | 'NORMAL' | 'HIGH' | 'URGENT';
 
 export interface InboxItemV1 {
   readonly schemaVersion: typeof ARTIFACT_INTAKE_SCHEMA_VERSION_V1;
@@ -31,6 +32,10 @@ export interface InboxItemV1 {
   readonly state: InboxItemStateV1;
   readonly createdAt: StrictUtcTimestampV1;
   readonly revision: number;
+  readonly assigneeId?: StableIdentifierV1;
+  readonly labels?: readonly string[];
+  readonly priority?: InboxPriorityV1;
+  readonly dueAt?: StrictUtcTimestampV1;
 }
 
 export type ArtifactIntakeErrorCodeV1 =
@@ -47,7 +52,9 @@ export type ArtifactIntakeErrorCodeV1 =
   | 'SIZE_MISMATCH'
   | 'MEDIA_MISMATCH'
   | 'SIZE_POLICY_EXCEEDED'
-  | 'SCAN_NOT_COMPLETE';
+  | 'SCAN_NOT_COMPLETE'
+  | 'INVALID_METADATA'
+  | 'REVISION_CONFLICT';
 
 export type ArtifactIntakeResultV1<TValue> =
   | { readonly accepted: true; readonly value: TValue }
@@ -146,6 +153,72 @@ export function transitionInboxItemV1(
   return accepted(Object.freeze({ ...item, state: nextState, revision: item.revision + 1 }));
 }
 
+/** IAE-013: metadata updates are revisioned and never change artifact identity or state. */
+export function updateInboxMetadataV1(
+  item: InboxItemV1,
+  input: {
+    readonly assigneeId?: unknown;
+    readonly labels?: unknown;
+    readonly priority?: unknown;
+    readonly dueAt?: unknown;
+    readonly expectedRevision: unknown;
+  },
+): ArtifactIntakeResultV1<InboxItemV1> {
+  if (
+    typeof input.expectedRevision !== 'number' ||
+    !Number.isSafeInteger(input.expectedRevision) ||
+    input.expectedRevision < 1
+  )
+    return rejected('INVALID_METADATA');
+  if (input.expectedRevision !== item.revision) return rejected('REVISION_CONFLICT');
+  let assigneeId = item.assigneeId;
+  if (input.assigneeId !== undefined) {
+    if (input.assigneeId === null) assigneeId = undefined;
+    else {
+      assigneeId = identifier(input.assigneeId);
+      if (!assigneeId) return rejected('INVALID_METADATA');
+    }
+  }
+  let labels = item.labels;
+  if (input.labels !== undefined) {
+    if (!Array.isArray(input.labels) || input.labels.length > 32)
+      return rejected('INVALID_METADATA');
+    const parsedLabels = input.labels.map((label) => text(label, 64));
+    if (
+      parsedLabels.some((label): label is undefined => label === undefined) ||
+      new Set(parsedLabels).size !== parsedLabels.length
+    )
+      return rejected('INVALID_METADATA');
+    labels = Object.freeze(parsedLabels as string[]);
+  }
+  let priority = item.priority;
+  if (input.priority !== undefined) {
+    if (!['LOW', 'NORMAL', 'HIGH', 'URGENT'].includes(input.priority as string))
+      return rejected('INVALID_METADATA');
+    priority = input.priority as InboxPriorityV1;
+  }
+  let dueAt = item.dueAt;
+  if (input.dueAt !== undefined) {
+    if (input.dueAt === null) dueAt = undefined;
+    else {
+      dueAt = timestamp(input.dueAt);
+      if (!dueAt) return rejected('INVALID_METADATA');
+    }
+  }
+  const next = { ...item, revision: item.revision + 1 };
+  if (input.assigneeId !== undefined) {
+    if (assigneeId === undefined) delete next.assigneeId;
+    else next.assigneeId = assigneeId;
+  }
+  if (labels !== undefined) next.labels = labels;
+  if (priority !== undefined) next.priority = priority;
+  if (input.dueAt !== undefined) {
+    if (dueAt === undefined) delete next.dueAt;
+    else next.dueAt = dueAt;
+  }
+  return accepted(Object.freeze(next));
+}
+
 export function finalizeArtifactAdmissionV1(input: {
   readonly artifact: ArtifactVersionV1;
   readonly actualSha256: unknown;