// @bun
var{defineProperty:z,getOwnPropertyNames:D,getOwnPropertyDescriptor:E}=Object,F=Object.prototype.hasOwnProperty;function G(f){return this[f]}var M=(f)=>{var j=(A??=new WeakMap).get(f),q;if(j)return j;if(j=z({},"__esModule",{value:!0}),f&&typeof f==="object"||typeof f==="function"){for(var u of D(f))if(!F.call(j,u))z(j,u,{get:G.bind(f,u),enumerable:!(q=E(f,u))||q.enumerable})}return A.set(f,j),j},A;var H=(f)=>f;function J(f,j){this[f]=H.bind(null,j)}var O=(f,j)=>{for(var q in j)z(f,q,{get:j[q],enumerable:!0,configurable:!0,set:J.bind(j,q)})};var P=(f,j)=>()=>(f&&(j=f(f=0)),j);import{compareVersions as B}from"compare-versions";var C=(f,j)=>`${f}.v${j}`;class L{items=new Map;register(f){let j=C(f.meta.key,f.meta.version);if(this.items.has(j))throw Error(`Duplicate migration ${j}`);return this.items.set(j,f),this}list(){return[...this.items.values()].sort((f,j)=>{let q=f.meta.key.localeCompare(j.meta.key);return q!==0?q:B(f.meta.version,j.meta.version)})}get(f,j){if(j!=null)return this.items.get(C(f,j));let q;for(let u of this.items.values()){if(u.meta.key!==f)continue;if(!q||B(u.meta.version,q.meta.version)>0)q=u}return q}}var S=[{id:"docs.tech.contracts.migrations",title:"MigrationSpec Overview",summary:"`MigrationSpec` provides a declarative plan for schema/data/validation steps so migrations can be generated, reviewed, and executed safely by tooling. Each spec captures ownership metadata, ordered up/down steps, and optional dependency information. Runtime tooling can consume the spec to run SQL/data scripts with pre/post checks and produce audit logs.",kind:"reference",visibility:"public",route:"/docs/tech/contracts/migrations",tags:["tech","contracts","migrations"],body:"# MigrationSpec Overview\n\n## Purpose\n\n`MigrationSpec` provides a declarative plan for schema/data/validation steps so migrations can be generated, reviewed, and executed safely by tooling. Each spec captures ownership metadata, ordered up/down steps, and optional dependency information. Runtime tooling can consume the spec to run SQL/data scripts with pre/post checks and produce audit logs.\n\n## Location\n\n- Spec + registry: `packages/libs/contracts/src/migrations.ts`\n- Tests: `packages/.../migrations.test.ts`\n\n## Schema\n\n```ts\nexport interface MigrationSpec {\n  meta: MigrationMeta;   // ownership metadata + { name, version }\n  plan: {\n    up: MigrationStep[];   // required forward plan\n    down?: MigrationStep[];// optional rollback steps\n  };\n  dependencies?: string[]; // optional list of migration keys this depends on\n}\n```\n\n- **MigrationStep**\n  - `kind`: `'schema' | 'data' | 'validation'`\n  - Shared fields: `description?`, `timeoutMs?`, `retries?`, `preChecks?`, `postChecks?`\n  - `schema`: `sql` string executed in transactional context\n  - `data`: arbitrary `script` (e.g., JS/TS snippet, path to file, instructions)\n  - `validation`: `assertion` expression verifying state (e.g., SQL returning boolean)\n- **MigrationCheck** (`preChecks`/`postChecks`)\n  - `description`: human context\n  - `expression`: expression or SQL snippet to evaluate before/after the step\n- **Dependencies**\n  - Array of migration keys (`\"boundedContext.namespace.timestamp_slug\"`) used to ensure the registry executes prerequisites first\n\n## Registry Usage\n\n```ts\nimport { MigrationRegistry } from '@contractspec/lib.contracts-spec/migrations';\nimport { AddUsersMigration } from './migrations/core.db.2025_01_add_users';\n\nconst registry = new MigrationRegistry();\nregistry.register(AddUsersMigration);\n\nconst migration = registry.get('core.db.2025_01_add_users');\nconst all = registry.list(); // sorted by name/version\n```\n\n## Authoring Guidelines\n\n1. Name migrations with timestamped slugs (`domain.db.YYYY_MM_description`) for clarity.\n2. Capture ownership metadata (`owners`, `tags`, `stability`) so tooling can route approvals.\n3. Prefer small, reversible steps. Use `plan.down` when safe; otherwise document fallback.\n4. Use `preChecks`/`postChecks` for critical invariants (row counts, schema existence).\n5. Specify dependencies explicitly to avoid parallel execution hazards.\n6. For large data scripts, use `script` as a pointer (URL, file path) rather than embedding code directly.\n\n## Tooling Roadmap\n\nUpcoming CLI support (Phase 4 plan):\n\n- `contractspec create --type migration` (scaffolds spec skeleton)\n- `contractspec build <migration>` (generate executor harness)\n- `contractspec migrate create/up/down/status` orchestration commands\n\nThe current implementation focuses on the spec/registry foundation so downstream tooling can be layered iteratively.\n\n"}];export{S as tech_contracts_migrations_DocBlocks,L as MigrationRegistry};
