# ISIS v2 WS06-009: 3D Provenance Integration

## Scope

`WS06-009` integrates first-class 3D provenance records into ISIS 3D package
contracts so downstream systems can trace:

- Source imagery used for reconstruction/control/reference.
- Canonical control inputs (ControlNet, IPAdapter, InstantID/manual).
- Post-process pipeline history with timestamped operations and parameter
  digests.

## Research Alignment

Implementation aligns with existing ISIS provenance systems and contracts:

- Output-registry provenance conventions in
  `apps/isis/output-registry/src/services/output.service.ts`.
- Existing control contract normalization in
  `apps/isis/generation-api/src/workflows/executor.ts`.
- Prior WS06 contract propagation approach for
  generation-api/output-registry/client 3D package schemas and types.

## Implemented Deliverables

1. Added reusable 3D provenance utilities in `@isis/3d-generation`:

- `buildThreeDProvenanceRecord`
- `validateThreeDProvenanceRecord`
- Strongly typed source-image/control-input/post-process records.

2. Integrated provenance generation into 3D workflow execution output:

- `threeDPackage.metadata.provenance` is now emitted for 3D jobs.
- Source images aggregate from direct input, parameterized references, and
  control sources.
- Control inputs are emitted from canonicalized control requests.
- Post-process history records reconstruction, quality, and packaging stages.

3. Propagated 3D provenance contract through:

- Generation API schemas and types.
- Output-registry schemas and types.
- ISIS client SDK types.

4. Added/extended tests to validate:

- Provenance utility behavior.
- Schema acceptance of provenance in 3D package metadata.
- Executor output includes populated 3D provenance records.

## Verification Commands

```bash
pnpm --filter @isis/3d-generation exec vitest run src/processing/three-d-provenance.spec.ts src/processing/dcc-export-bundles.spec.ts src/processing/engine-export-bundles.spec.ts src/processing/mesh-quality-validator.spec.ts src/processing/pbr-texture-validator.spec.ts src/processing/uv-texel-quality-validator.spec.ts src/processing/lod-pipeline-validator.spec.ts src/processing/rig-readiness-validator.spec.ts
pnpm --filter @isis/generation-api exec vitest run src/schemas/job.schema.spec.ts src/workflows/executor.spec.ts
pnpm --filter @isis/output-registry exec vitest run src/schemas/output.schema.spec.ts
pnpm --filter @isis/3d-generation exec tsc -p tsconfig.json --noEmit
pnpm --filter @isis/workflows exec vitest run src/workflows.spec.ts
pnpm --filter @isis/workflows exec tsc -p tsconfig.json --noEmit
pnpm --filter @isis/generation-api exec tsc -p tsconfig.json --noEmit
pnpm --filter @isis/output-registry exec tsc -p tsconfig.json --noEmit
node scripts/isis/validate-v2-compliance-gate.mjs
```
