typescript-decompiler/docs/phase-docs/phase-1-deterministic-ingest.md

Phase 1 — deterministic ingest

Goal

Turn an upstream bundle snapshot into deterministic segment records and a canonical source projection that later phases can diff, name, and replay transforms against.

Script

scripts/ingest-bundle.js

Inputs

• --input <bundle.js>
• --run-id <id>
• --previous <runs/<id>/manifest.json> optional
• optional upstream snapshot metadata for release manifests

Responsibilities

1. parse the bundle with Babel
2. detect segment or module boundaries deterministically
3. for each segment/module:
   • capture source slice and AST node type
   • generate canonical pretty-printed code
   • normalize identifiers for hashing where appropriate
   • compute rawHash, normalizedHash, and shapeHash
4. emit:
   • runs/<run-id>/manifest.json
   • runs/<run-id>/segments.jsonl
   • runs/<run-id>/bundle.formatted.js
   • runs/<run-id>/reports/summary.md

Release-oriented requirements

• manifest must identify the upstream snapshot being ingested
• output must be deterministic so identical upstream snapshots reuse the same run identity inputs
• segment IDs should persist when matching is strong, but minting new IDs is acceptable when reshaping is severe
• ingest output is the base tree for later relabeling and transform replay

Verification

• run ingest against a fixture bundle
• confirm segment count is non-zero
• confirm manifest and JSONL are emitted
• spot-check representative segments for stable formatting