@skillcap/gdh 0.22.0 → 0.24.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (150) hide show
  1. package/INSTALL-BUNDLE.json +1 -1
  2. package/RELEASE-SPAN-UPDATE-CONTRACTS.json +129 -0
  3. package/node_modules/@gdh/adapters/dist/authoring-hook-render.d.ts.map +1 -1
  4. package/node_modules/@gdh/adapters/dist/authoring-hook-render.js +9 -2
  5. package/node_modules/@gdh/adapters/dist/authoring-hook-render.js.map +1 -1
  6. package/node_modules/@gdh/adapters/dist/claude-statusline-render.d.ts.map +1 -1
  7. package/node_modules/@gdh/adapters/dist/claude-statusline-render.js +2 -1
  8. package/node_modules/@gdh/adapters/dist/claude-statusline-render.js.map +1 -1
  9. package/node_modules/@gdh/adapters/dist/claude-update-hook-render.d.ts.map +1 -1
  10. package/node_modules/@gdh/adapters/dist/claude-update-hook-render.js +2 -1
  11. package/node_modules/@gdh/adapters/dist/claude-update-hook-render.js.map +1 -1
  12. package/node_modules/@gdh/adapters/dist/claude-update-worker-render.d.ts.map +1 -1
  13. package/node_modules/@gdh/adapters/dist/claude-update-worker-render.js +2 -1
  14. package/node_modules/@gdh/adapters/dist/claude-update-worker-render.js.map +1 -1
  15. package/node_modules/@gdh/adapters/dist/deferred-actions-advisory.d.ts +71 -0
  16. package/node_modules/@gdh/adapters/dist/deferred-actions-advisory.d.ts.map +1 -0
  17. package/node_modules/@gdh/adapters/dist/deferred-actions-advisory.js +89 -0
  18. package/node_modules/@gdh/adapters/dist/deferred-actions-advisory.js.map +1 -0
  19. package/node_modules/@gdh/adapters/dist/durable-backup.d.ts +209 -0
  20. package/node_modules/@gdh/adapters/dist/durable-backup.d.ts.map +1 -0
  21. package/node_modules/@gdh/adapters/dist/durable-backup.js +346 -0
  22. package/node_modules/@gdh/adapters/dist/durable-backup.js.map +1 -0
  23. package/node_modules/@gdh/adapters/dist/index.d.ts +10 -1
  24. package/node_modules/@gdh/adapters/dist/index.d.ts.map +1 -1
  25. package/node_modules/@gdh/adapters/dist/index.js +24 -2
  26. package/node_modules/@gdh/adapters/dist/index.js.map +1 -1
  27. package/node_modules/@gdh/adapters/dist/inventory-sweep.d.ts +53 -0
  28. package/node_modules/@gdh/adapters/dist/inventory-sweep.d.ts.map +1 -0
  29. package/node_modules/@gdh/adapters/dist/inventory-sweep.js +98 -0
  30. package/node_modules/@gdh/adapters/dist/inventory-sweep.js.map +1 -0
  31. package/node_modules/@gdh/adapters/dist/process-orchestration.d.ts +223 -0
  32. package/node_modules/@gdh/adapters/dist/process-orchestration.d.ts.map +1 -0
  33. package/node_modules/@gdh/adapters/dist/process-orchestration.js +368 -0
  34. package/node_modules/@gdh/adapters/dist/process-orchestration.js.map +1 -0
  35. package/node_modules/@gdh/adapters/dist/self-update-mechanics.d.ts +157 -14
  36. package/node_modules/@gdh/adapters/dist/self-update-mechanics.d.ts.map +1 -1
  37. package/node_modules/@gdh/adapters/dist/self-update-mechanics.js +570 -89
  38. package/node_modules/@gdh/adapters/dist/self-update-mechanics.js.map +1 -1
  39. package/node_modules/@gdh/adapters/dist/skill-rendering.d.ts.map +1 -1
  40. package/node_modules/@gdh/adapters/dist/skill-rendering.js +25 -0
  41. package/node_modules/@gdh/adapters/dist/skill-rendering.js.map +1 -1
  42. package/node_modules/@gdh/adapters/package.json +8 -8
  43. package/node_modules/@gdh/authoring/dist/diagnostics-broker-contract.d.ts +112 -0
  44. package/node_modules/@gdh/authoring/dist/diagnostics-broker-contract.d.ts.map +1 -0
  45. package/node_modules/@gdh/authoring/dist/diagnostics-broker-contract.js +264 -0
  46. package/node_modules/@gdh/authoring/dist/diagnostics-broker-contract.js.map +1 -0
  47. package/node_modules/@gdh/authoring/dist/diagnostics-broker.d.ts +92 -0
  48. package/node_modules/@gdh/authoring/dist/diagnostics-broker.d.ts.map +1 -0
  49. package/node_modules/@gdh/authoring/dist/diagnostics-broker.js +532 -0
  50. package/node_modules/@gdh/authoring/dist/diagnostics-broker.js.map +1 -0
  51. package/node_modules/@gdh/authoring/dist/index.d.ts +1 -0
  52. package/node_modules/@gdh/authoring/dist/index.d.ts.map +1 -1
  53. package/node_modules/@gdh/authoring/dist/index.js +1 -0
  54. package/node_modules/@gdh/authoring/dist/index.js.map +1 -1
  55. package/node_modules/@gdh/authoring/dist/lsp-client.d.ts +16 -0
  56. package/node_modules/@gdh/authoring/dist/lsp-client.d.ts.map +1 -1
  57. package/node_modules/@gdh/authoring/dist/lsp-client.js +24 -0
  58. package/node_modules/@gdh/authoring/dist/lsp-client.js.map +1 -1
  59. package/node_modules/@gdh/authoring/dist/lsp.d.ts.map +1 -1
  60. package/node_modules/@gdh/authoring/dist/lsp.js +123 -2
  61. package/node_modules/@gdh/authoring/dist/lsp.js.map +1 -1
  62. package/node_modules/@gdh/authoring/package.json +2 -2
  63. package/node_modules/@gdh/cli/dist/index.d.ts +9 -0
  64. package/node_modules/@gdh/cli/dist/index.d.ts.map +1 -1
  65. package/node_modules/@gdh/cli/dist/index.js +423 -5
  66. package/node_modules/@gdh/cli/dist/index.js.map +1 -1
  67. package/node_modules/@gdh/cli/dist/migrate.d.ts +152 -1
  68. package/node_modules/@gdh/cli/dist/migrate.d.ts.map +1 -1
  69. package/node_modules/@gdh/cli/dist/migrate.js +295 -9
  70. package/node_modules/@gdh/cli/dist/migrate.js.map +1 -1
  71. package/node_modules/@gdh/cli/dist/self-update.d.ts +14 -0
  72. package/node_modules/@gdh/cli/dist/self-update.d.ts.map +1 -1
  73. package/node_modules/@gdh/cli/dist/self-update.js +197 -15
  74. package/node_modules/@gdh/cli/dist/self-update.js.map +1 -1
  75. package/node_modules/@gdh/cli/package.json +10 -10
  76. package/node_modules/@gdh/core/dist/index.d.ts +209 -6
  77. package/node_modules/@gdh/core/dist/index.d.ts.map +1 -1
  78. package/node_modules/@gdh/core/dist/index.js +28 -5
  79. package/node_modules/@gdh/core/dist/index.js.map +1 -1
  80. package/node_modules/@gdh/core/dist/migrations/entries/s2c2_to_s2c3_rules_schema_v2_to_v3.d.ts +3 -0
  81. package/node_modules/@gdh/core/dist/migrations/entries/s2c2_to_s2c3_rules_schema_v2_to_v3.d.ts.map +1 -0
  82. package/node_modules/@gdh/core/dist/migrations/entries/s2c2_to_s2c3_rules_schema_v2_to_v3.js +247 -0
  83. package/node_modules/@gdh/core/dist/migrations/entries/s2c2_to_s2c3_rules_schema_v2_to_v3.js.map +1 -0
  84. package/node_modules/@gdh/core/dist/migrations/entries/s3c8_to_s3c9_register_runtime_bridge_autoload.d.ts +3 -0
  85. package/node_modules/@gdh/core/dist/migrations/entries/s3c8_to_s3c9_register_runtime_bridge_autoload.d.ts.map +1 -0
  86. package/node_modules/@gdh/core/dist/migrations/entries/s3c8_to_s3c9_register_runtime_bridge_autoload.js +152 -0
  87. package/node_modules/@gdh/core/dist/migrations/entries/s3c8_to_s3c9_register_runtime_bridge_autoload.js.map +1 -0
  88. package/node_modules/@gdh/core/dist/migrations/envelopes/envelope-output-validator.d.ts +3 -0
  89. package/node_modules/@gdh/core/dist/migrations/envelopes/envelope-output-validator.d.ts.map +1 -0
  90. package/node_modules/@gdh/core/dist/migrations/envelopes/envelope-output-validator.js +67 -0
  91. package/node_modules/@gdh/core/dist/migrations/envelopes/envelope-output-validator.js.map +1 -0
  92. package/node_modules/@gdh/core/dist/migrations/envelopes/index.d.ts +37 -0
  93. package/node_modules/@gdh/core/dist/migrations/envelopes/index.d.ts.map +1 -0
  94. package/node_modules/@gdh/core/dist/migrations/envelopes/index.js +60 -0
  95. package/node_modules/@gdh/core/dist/migrations/envelopes/index.js.map +1 -0
  96. package/node_modules/@gdh/core/dist/migrations/envelopes/types.d.ts +121 -0
  97. package/node_modules/@gdh/core/dist/migrations/envelopes/types.d.ts.map +1 -0
  98. package/node_modules/@gdh/core/dist/migrations/envelopes/types.js +2 -0
  99. package/node_modules/@gdh/core/dist/migrations/envelopes/types.js.map +1 -0
  100. package/node_modules/@gdh/core/dist/migrations/golden-harness.d.ts +40 -0
  101. package/node_modules/@gdh/core/dist/migrations/golden-harness.d.ts.map +1 -0
  102. package/node_modules/@gdh/core/dist/migrations/golden-harness.js +71 -0
  103. package/node_modules/@gdh/core/dist/migrations/golden-harness.js.map +1 -0
  104. package/node_modules/@gdh/core/dist/migrations/managed-surface-classes.d.ts +322 -0
  105. package/node_modules/@gdh/core/dist/migrations/managed-surface-classes.d.ts.map +1 -0
  106. package/node_modules/@gdh/core/dist/migrations/managed-surface-classes.js +384 -0
  107. package/node_modules/@gdh/core/dist/migrations/managed-surface-classes.js.map +1 -0
  108. package/node_modules/@gdh/core/dist/migrations/probes.d.ts +58 -0
  109. package/node_modules/@gdh/core/dist/migrations/probes.d.ts.map +1 -0
  110. package/node_modules/@gdh/core/dist/migrations/probes.js +112 -0
  111. package/node_modules/@gdh/core/dist/migrations/probes.js.map +1 -0
  112. package/node_modules/@gdh/core/dist/migrations/registry.d.ts +205 -0
  113. package/node_modules/@gdh/core/dist/migrations/registry.d.ts.map +1 -0
  114. package/node_modules/@gdh/core/dist/migrations/registry.js +214 -0
  115. package/node_modules/@gdh/core/dist/migrations/registry.js.map +1 -0
  116. package/node_modules/@gdh/core/dist/state/atomic-write.d.ts +19 -0
  117. package/node_modules/@gdh/core/dist/state/atomic-write.d.ts.map +1 -0
  118. package/node_modules/@gdh/core/dist/state/atomic-write.js +34 -0
  119. package/node_modules/@gdh/core/dist/state/atomic-write.js.map +1 -0
  120. package/node_modules/@gdh/core/dist/state/migration-state.d.ts +135 -0
  121. package/node_modules/@gdh/core/dist/state/migration-state.d.ts.map +1 -0
  122. package/node_modules/@gdh/core/dist/state/migration-state.js +186 -0
  123. package/node_modules/@gdh/core/dist/state/migration-state.js.map +1 -0
  124. package/node_modules/@gdh/core/dist/state/processes-snapshot.d.ts +72 -0
  125. package/node_modules/@gdh/core/dist/state/processes-snapshot.d.ts.map +1 -0
  126. package/node_modules/@gdh/core/dist/state/processes-snapshot.js +113 -0
  127. package/node_modules/@gdh/core/dist/state/processes-snapshot.js.map +1 -0
  128. package/node_modules/@gdh/core/dist/state/render-inventory.d.ts +54 -0
  129. package/node_modules/@gdh/core/dist/state/render-inventory.d.ts.map +1 -0
  130. package/node_modules/@gdh/core/dist/state/render-inventory.js +77 -0
  131. package/node_modules/@gdh/core/dist/state/render-inventory.js.map +1 -0
  132. package/node_modules/@gdh/core/package.json +1 -1
  133. package/node_modules/@gdh/docs/dist/agent-contract.d.ts.map +1 -1
  134. package/node_modules/@gdh/docs/dist/agent-contract.js +2 -1
  135. package/node_modules/@gdh/docs/dist/agent-contract.js.map +1 -1
  136. package/node_modules/@gdh/docs/dist/guidance.d.ts.map +1 -1
  137. package/node_modules/@gdh/docs/dist/guidance.js +14 -7
  138. package/node_modules/@gdh/docs/dist/guidance.js.map +1 -1
  139. package/node_modules/@gdh/docs/package.json +2 -2
  140. package/node_modules/@gdh/mcp/dist/index.d.ts.map +1 -1
  141. package/node_modules/@gdh/mcp/dist/index.js +77 -1
  142. package/node_modules/@gdh/mcp/dist/index.js.map +1 -1
  143. package/node_modules/@gdh/mcp/package.json +8 -8
  144. package/node_modules/@gdh/observability/package.json +2 -2
  145. package/node_modules/@gdh/runtime/dist/bridge-surface.js +63 -2
  146. package/node_modules/@gdh/runtime/dist/bridge-surface.js.map +1 -1
  147. package/node_modules/@gdh/runtime/package.json +2 -2
  148. package/node_modules/@gdh/scan/package.json +3 -3
  149. package/node_modules/@gdh/verify/package.json +7 -7
  150. package/package.json +11 -11
@@ -0,0 +1,37 @@
1
+ import type { GdhMigrationEnvelope } from "./types.js";
2
+ export declare function isEnvelopeSlug(candidate: unknown): candidate is string;
3
+ /**
4
+ * Static slug→envelope manifest (D-04).
5
+ *
6
+ * Resolution is a `Record` lookup; NO dynamic ES-module loader — that would
7
+ * add path-traversal surface and lose the static type guarantee that every
8
+ * shipped envelope is enumerable for tests (the defense-in-depth invariant
9
+ * in `./index.test.ts` iterates every entry to assert
10
+ * `key === envelope.envelope_ref` and `isEnvelopeSlug(key)`).
11
+ *
12
+ * Phase 73 ships this empty: no Phase 72 registry entry has `envelope_ref`
13
+ * set (D-25 of Phase 72 reserves `envelope_ref` as the typed escape hatch
14
+ * for genuinely semantic transforms; the only Phase 72 entry,
15
+ * `entry_s2c2_to_s2c3_rules_schema`, is mechanical Rule A). The first real
16
+ * envelope-using migration in a later milestone adds a line to this map by:
17
+ *
18
+ * 1. Creating `packages/core/src/migrations/envelopes/<slug>.ts` exporting
19
+ * a typed `GdhMigrationEnvelope` whose `envelope_ref === <slug>`.
20
+ * 2. Adding `<slug>: <imported envelope>` to this object literal.
21
+ * 3. Adding `envelope_ref: "<slug>"` to the corresponding `GdhMigrationEntry`.
22
+ *
23
+ * Threat register reference: T-73-01-03 (inline-literal envelope spoofing).
24
+ * Mitigation = the manifest is the single registration path; `applyMigrationChain`
25
+ * (Plan 03) only consumes `resolveEnvelopeBySlug(entry.envelope_ref)` and
26
+ * never accepts an inline-literal envelope object.
27
+ */
28
+ export declare const ENVELOPE_REGISTRY: {};
29
+ /**
30
+ * Resolve a slug to its registered envelope, or null if the slug is malformed
31
+ * or unknown.
32
+ *
33
+ * Two-step gate: shape regex → manifest lookup. Both steps fail closed; no
34
+ * filesystem access at any step.
35
+ */
36
+ export declare function resolveEnvelopeBySlug(slug: string): GdhMigrationEnvelope | null;
37
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/migrations/envelopes/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAkBvD,wBAAgB,cAAc,CAAC,SAAS,EAAE,OAAO,GAAG,SAAS,IAAI,MAAM,CAEtE;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,iBAAiB,IAEqC,CAAC;AAEpE;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,GACX,oBAAoB,GAAG,IAAI,CAM7B"}
@@ -0,0 +1,60 @@
1
+ /**
2
+ * Slug shape (D-04): lower-case ASCII letter start, then lower-case ASCII
3
+ * letters, digits, or underscores. Tight enough that a slug can never escape
4
+ * the `envelopes/` directory or be used as a path-traversal vector.
5
+ *
6
+ * Defense-in-depth: even though `resolveEnvelopeBySlug` is a `Record` lookup
7
+ * (no `path.join`, no `fs`), the regex shape gate prevents agent-supplied
8
+ * `envelope_ref` strings from carrying separators or relative segments —
9
+ * the staleness check and Phase 74 migration-assist skill round-trip the
10
+ * slug through this regex before any consumer sees it.
11
+ *
12
+ * Threat register reference: T-73-01-01 (tampering / information disclosure
13
+ * via slug-as-path-component).
14
+ */
15
+ const SLUG_REGEX = /^[a-z][a-z0-9_]*$/;
16
+ export function isEnvelopeSlug(candidate) {
17
+ return typeof candidate === "string" && SLUG_REGEX.test(candidate);
18
+ }
19
+ /**
20
+ * Static slug→envelope manifest (D-04).
21
+ *
22
+ * Resolution is a `Record` lookup; NO dynamic ES-module loader — that would
23
+ * add path-traversal surface and lose the static type guarantee that every
24
+ * shipped envelope is enumerable for tests (the defense-in-depth invariant
25
+ * in `./index.test.ts` iterates every entry to assert
26
+ * `key === envelope.envelope_ref` and `isEnvelopeSlug(key)`).
27
+ *
28
+ * Phase 73 ships this empty: no Phase 72 registry entry has `envelope_ref`
29
+ * set (D-25 of Phase 72 reserves `envelope_ref` as the typed escape hatch
30
+ * for genuinely semantic transforms; the only Phase 72 entry,
31
+ * `entry_s2c2_to_s2c3_rules_schema`, is mechanical Rule A). The first real
32
+ * envelope-using migration in a later milestone adds a line to this map by:
33
+ *
34
+ * 1. Creating `packages/core/src/migrations/envelopes/<slug>.ts` exporting
35
+ * a typed `GdhMigrationEnvelope` whose `envelope_ref === <slug>`.
36
+ * 2. Adding `<slug>: <imported envelope>` to this object literal.
37
+ * 3. Adding `envelope_ref: "<slug>"` to the corresponding `GdhMigrationEntry`.
38
+ *
39
+ * Threat register reference: T-73-01-03 (inline-literal envelope spoofing).
40
+ * Mitigation = the manifest is the single registration path; `applyMigrationChain`
41
+ * (Plan 03) only consumes `resolveEnvelopeBySlug(entry.envelope_ref)` and
42
+ * never accepts an inline-literal envelope object.
43
+ */
44
+ export const ENVELOPE_REGISTRY = {
45
+ // [envelope_<slug>.envelope_ref]: envelope_<slug>, // future
46
+ };
47
+ /**
48
+ * Resolve a slug to its registered envelope, or null if the slug is malformed
49
+ * or unknown.
50
+ *
51
+ * Two-step gate: shape regex → manifest lookup. Both steps fail closed; no
52
+ * filesystem access at any step.
53
+ */
54
+ export function resolveEnvelopeBySlug(slug) {
55
+ if (!isEnvelopeSlug(slug))
56
+ return null;
57
+ return (ENVELOPE_REGISTRY[slug] ??
58
+ null);
59
+ }
60
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/migrations/envelopes/index.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,GAAG,mBAAmB,CAAC;AAEvC,MAAM,UAAU,cAAc,CAAC,SAAkB;IAC/C,OAAO,OAAO,SAAS,KAAK,QAAQ,IAAI,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;AACrE,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG;AAC/B,8DAA8D;CACG,CAAC;AAEpE;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CACnC,IAAY;IAEZ,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACvC,OAAO,CACJ,iBAAoE,CAAC,IAAI,CAAC;QAC3E,IAAI,CACL,CAAC;AACJ,CAAC"}
@@ -0,0 +1,121 @@
1
+ import type { GdhMigrationVersionPair } from "../registry.js";
2
+ /**
3
+ * Phase 73 migration envelope schema (D-01 / D-02 / D-03 / D-04).
4
+ *
5
+ * The envelope is the typed escape hatch for genuinely semantic migrations
6
+ * that mechanical Rule A (deterministic transform) cannot express. Every
7
+ * field name is `snake_case` to match the on-disk JSON conventions Phase 72
8
+ * established for `migration.json` (`recorded_at`, `from_pin`, `to_pin`,
9
+ * `output_contract`, …); per-field `readonly` mirrors the immutability
10
+ * pattern at `packages/core/src/migrations/registry.ts:31-56`.
11
+ *
12
+ * This file is the single shared schema surface consumed by:
13
+ * - `applyMigrationChain` (Plan 03) — emits the envelope when an entry
14
+ * declares `envelope_ref`.
15
+ * - `gdh migration record-envelope-result` (Plan 05) — validates the
16
+ * agent-supplied output_contract against `GdhMigrationEnvelopeOutput`
17
+ * via `isEnvelopeOutput` (`./envelope-output-validator.ts`).
18
+ * - The static slug→envelope manifest (`./index.ts`).
19
+ *
20
+ * D-01 explicitly excludes a clarifying-questions mandate field (it would
21
+ * conflict with batch `gdh self-update` runs). D-03 explicitly excludes a
22
+ * per-envelope output_contract extension slot in v1.18 (YAGNI; reintroduce
23
+ * when envelope variance is real). Per D-04, `envelope_ref` is a slug only
24
+ * — inline-literal envelope objects on `GdhMigrationEntry.envelope_ref` are
25
+ * unsupported by construction.
26
+ */
27
+ /**
28
+ * Structured mandate (D-01).
29
+ *
30
+ * `acceptance_criteria` MUST be enumerated at authoring time so the agent
31
+ * has a verifiable rubric for its `output_contract` and downstream evidence
32
+ * recording knows what "done" looks like.
33
+ */
34
+ export interface GdhMigrationEnvelopeMandate {
35
+ readonly instruction: string;
36
+ readonly acceptance_criteria: readonly string[];
37
+ readonly examples?: readonly string[];
38
+ }
39
+ /**
40
+ * Tool scope (D-02). Glob patterns mirror gitignore semantics the author
41
+ * already knows. No deny-list carve-outs in v1.18 (YAGNI).
42
+ */
43
+ export interface GdhMigrationEnvelopeToolScope {
44
+ /** Glob patterns the agent MAY read from. */
45
+ readonly read: readonly string[];
46
+ /** Glob patterns the agent MAY write to. */
47
+ readonly write: readonly string[];
48
+ }
49
+ /**
50
+ * Seed shape for `apply.changes` (D-03). Phase 73 stores the array as
51
+ * evidence; later phases that ship a real envelope-using migration define
52
+ * concrete consumers. Keep field names primitive and JSON-safe so the
53
+ * recorded slot in `migration.json` remains round-trippable through
54
+ * `JSON.parse`/`JSON.stringify` without per-shape codecs.
55
+ */
56
+ export type GdhFileChange = {
57
+ readonly kind: "rewrite";
58
+ readonly relativePath: string;
59
+ readonly content: string;
60
+ } | {
61
+ readonly kind: "delete";
62
+ readonly relativePath: string;
63
+ };
64
+ /**
65
+ * Typed discriminated union for the agent's output (D-03).
66
+ *
67
+ * Three named outcomes:
68
+ * - `apply` — agent produced a concrete change set; `migration.json`
69
+ * records `changes` as evidence.
70
+ * - `abort` — agent declined; `reason` is recorded for audit trail.
71
+ * - `needs_clarification` — agent wants questions answered before applying;
72
+ * `questions` are recorded so the operator/next session can resolve them.
73
+ *
74
+ * D-03 explicitly excludes a per-envelope extension slot — adding one now
75
+ * would invite untyped expansion ahead of any real envelope-using migration.
76
+ */
77
+ export type GdhMigrationEnvelopeOutput = {
78
+ readonly state: "apply";
79
+ readonly changes: readonly GdhFileChange[];
80
+ } | {
81
+ readonly state: "abort";
82
+ readonly reason: string;
83
+ } | {
84
+ readonly state: "needs_clarification";
85
+ readonly questions: readonly string[];
86
+ };
87
+ /**
88
+ * Migration envelope (D-04).
89
+ *
90
+ * Each envelope file under `packages/core/src/migrations/envelopes/<slug>.ts`
91
+ * exports a single typed `GdhMigrationEnvelope`. `envelope_ref` MUST equal
92
+ * the file basename and pass `isEnvelopeSlug` (`./index.ts`); the
93
+ * defense-in-depth invariant test in `./index.test.ts` enforces that
94
+ * registry key === entry's `envelope_ref` for every shipped envelope.
95
+ *
96
+ * `from`/`to` drive the D-10 staleness gate: a previously-recorded envelope
97
+ * result is valid only when `(envelope_ref, from_pin, to_pin)` all match the
98
+ * current chain step's bump pair. Pin change → stale → re-emit envelope.
99
+ *
100
+ * `fallback_note` reminds the inline-running agent (host that cannot spawn
101
+ * subagents) that the same mandate, tool_scope, and output_contract apply;
102
+ * tool scope is discipline-bound rather than enforced by a sandboxed
103
+ * subagent (per MIGRATION-WORKFLOW.md §4.2).
104
+ */
105
+ export interface GdhMigrationEnvelope {
106
+ /** Slug == file basename under envelopes/ (D-04). Lower-case + underscore + digit only. */
107
+ readonly envelope_ref: string;
108
+ /** From-pair the envelope is valid for. Used by the D-10 staleness gate. */
109
+ readonly from: GdhMigrationVersionPair;
110
+ /** To-pair the envelope is valid for. */
111
+ readonly to: GdhMigrationVersionPair;
112
+ readonly mandate: GdhMigrationEnvelopeMandate;
113
+ readonly tool_scope: GdhMigrationEnvelopeToolScope;
114
+ /**
115
+ * Identical mandate prompt and output_contract between subagent and inline
116
+ * paths (MIGRATION-WORKFLOW.md §4.2). The fallback note reminds the
117
+ * inline-running agent that tool scope is discipline-bound.
118
+ */
119
+ readonly fallback_note: string;
120
+ }
121
+ //# sourceMappingURL=types.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/migrations/envelopes/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAE9D;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH;;;;;;GAMG;AACH,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,mBAAmB,EAAE,SAAS,MAAM,EAAE,CAAC;IAChD,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC;AAED;;;GAGG;AACH,MAAM,WAAW,6BAA6B;IAC5C,6CAA6C;IAC7C,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,4CAA4C;IAC5C,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GACrB;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACrF;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAAC;AAE/D;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,0BAA0B,GAClC;IAAE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,SAAS,aAAa,EAAE,CAAA;CAAE,GACvE;IAAE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACpD;IAAE,QAAQ,CAAC,KAAK,EAAE,qBAAqB,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,CAAC;AAErF;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,oBAAoB;IAEnC,2FAA2F;IAC3F,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,4EAA4E;IAC5E,QAAQ,CAAC,IAAI,EAAE,uBAAuB,CAAC;IACvC,yCAAyC;IACzC,QAAQ,CAAC,EAAE,EAAE,uBAAuB,CAAC;IACrC,QAAQ,CAAC,OAAO,EAAE,2BAA2B,CAAC;IAC9C,QAAQ,CAAC,UAAU,EAAE,6BAA6B,CAAC;IACnD;;;;OAIG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC"}
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=types.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/migrations/envelopes/types.ts"],"names":[],"mappings":""}
@@ -0,0 +1,40 @@
1
+ /**
2
+ * Per-entry golden fixture harness for migration registry entries.
3
+ *
4
+ * Provides `runMigrationGolden(entry, fixturePath)` — reads `<fixturePath>/before/`,
5
+ * runs the entry's mechanical transform (Phase 72) or future subagent envelope
6
+ * (Phase 73), and asserts byte-equal match against `<fixturePath>/after/`.
7
+ *
8
+ * Phase 71 ships the harness scaffold + one stub golden test that proves the
9
+ * harness works against a noop transform. Phase 72 authors real registry
10
+ * entries that consume the harness. Per CONTEXT.md D-15 / D-16: the harness
11
+ * is a pure utility with no registry dependency — Phase 72's registry imports
12
+ * the harness, not the other way around.
13
+ *
14
+ * Consumers:
15
+ * - Phase 71: stub test in golden-harness.test.ts proves the harness works.
16
+ * - Phase 72: every migration registry entry's per-entry golden test.
17
+ *
18
+ * Per-entry fixture layout (CONTEXT.md D-17):
19
+ * tests/fixtures/migration-goldens/<entry-id>/
20
+ * before/ <- input file tree, paths relative to the per-entry root
21
+ * after/ <- expected output file tree, same path scheme
22
+ *
23
+ * Comparison semantics:
24
+ * - Default: byte-equal on every file declared in `after/`.
25
+ * - Class-2 user-data goldens (Phase 72) may opt into structural
26
+ * comparison via an entry-level comparator override (extension point;
27
+ * not implemented in Phase 71).
28
+ */
29
+ export interface GdhMigrationGoldenInputs {
30
+ readonly files: ReadonlyMap<string, string>;
31
+ }
32
+ export interface GdhMigrationGoldenOutputs {
33
+ readonly files: ReadonlyMap<string, string>;
34
+ }
35
+ export interface GdhMigrationGoldenEntry {
36
+ readonly id: string;
37
+ readonly transform: (input: GdhMigrationGoldenInputs) => Promise<GdhMigrationGoldenOutputs>;
38
+ }
39
+ export declare function runMigrationGolden(entry: GdhMigrationGoldenEntry, fixturePath: string): Promise<void>;
40
+ //# sourceMappingURL=golden-harness.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"golden-harness.d.ts","sourceRoot":"","sources":["../../src/migrations/golden-harness.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAKH,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC7C;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC7C;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,SAAS,EAAE,CAClB,KAAK,EAAE,wBAAwB,KAC5B,OAAO,CAAC,yBAAyB,CAAC,CAAC;CACzC;AA0BD,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,uBAAuB,EAC9B,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,IAAI,CAAC,CAgCf"}
@@ -0,0 +1,71 @@
1
+ /**
2
+ * Per-entry golden fixture harness for migration registry entries.
3
+ *
4
+ * Provides `runMigrationGolden(entry, fixturePath)` — reads `<fixturePath>/before/`,
5
+ * runs the entry's mechanical transform (Phase 72) or future subagent envelope
6
+ * (Phase 73), and asserts byte-equal match against `<fixturePath>/after/`.
7
+ *
8
+ * Phase 71 ships the harness scaffold + one stub golden test that proves the
9
+ * harness works against a noop transform. Phase 72 authors real registry
10
+ * entries that consume the harness. Per CONTEXT.md D-15 / D-16: the harness
11
+ * is a pure utility with no registry dependency — Phase 72's registry imports
12
+ * the harness, not the other way around.
13
+ *
14
+ * Consumers:
15
+ * - Phase 71: stub test in golden-harness.test.ts proves the harness works.
16
+ * - Phase 72: every migration registry entry's per-entry golden test.
17
+ *
18
+ * Per-entry fixture layout (CONTEXT.md D-17):
19
+ * tests/fixtures/migration-goldens/<entry-id>/
20
+ * before/ <- input file tree, paths relative to the per-entry root
21
+ * after/ <- expected output file tree, same path scheme
22
+ *
23
+ * Comparison semantics:
24
+ * - Default: byte-equal on every file declared in `after/`.
25
+ * - Class-2 user-data goldens (Phase 72) may opt into structural
26
+ * comparison via an entry-level comparator override (extension point;
27
+ * not implemented in Phase 71).
28
+ */
29
+ import fs from "node:fs/promises";
30
+ import path from "node:path";
31
+ async function readFixtureTree(rootPath) {
32
+ const files = new Map();
33
+ async function walk(currentDir, relativePrefix) {
34
+ const entries = await fs.readdir(currentDir, { withFileTypes: true });
35
+ for (const entry of entries) {
36
+ const entryPath = path.join(currentDir, entry.name);
37
+ const entryRelative = relativePrefix === "" ? entry.name : `${relativePrefix}/${entry.name}`;
38
+ if (entry.isDirectory()) {
39
+ await walk(entryPath, entryRelative);
40
+ }
41
+ else if (entry.isFile()) {
42
+ files.set(entryRelative, await fs.readFile(entryPath, "utf8"));
43
+ }
44
+ }
45
+ }
46
+ await walk(rootPath, "");
47
+ return files;
48
+ }
49
+ export async function runMigrationGolden(entry, fixturePath) {
50
+ const beforeFiles = await readFixtureTree(path.join(fixturePath, "before"));
51
+ const expectedAfterFiles = await readFixtureTree(path.join(fixturePath, "after"));
52
+ const result = await entry.transform({ files: beforeFiles });
53
+ const actualAfterFiles = result.files;
54
+ // 1. Every expected file must be present and byte-equal.
55
+ for (const [relativePath, expectedContent] of expectedAfterFiles) {
56
+ if (!actualAfterFiles.has(relativePath)) {
57
+ throw new Error(`Migration golden mismatch: missing expected output file "${relativePath}" for entry "${entry.id}".`);
58
+ }
59
+ const actualContent = actualAfterFiles.get(relativePath);
60
+ if (actualContent !== expectedContent) {
61
+ throw new Error(`Migration golden mismatch: content differs at "${relativePath}" for entry "${entry.id}".`);
62
+ }
63
+ }
64
+ // 2. Orphan detection — no unexpected output files.
65
+ for (const relativePath of actualAfterFiles.keys()) {
66
+ if (!expectedAfterFiles.has(relativePath)) {
67
+ throw new Error(`Migration golden mismatch: unexpected output file "${relativePath}" produced by entry "${entry.id}".`);
68
+ }
69
+ }
70
+ }
71
+ //# sourceMappingURL=golden-harness.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"golden-harness.js","sourceRoot":"","sources":["../../src/migrations/golden-harness.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAClC,OAAO,IAAI,MAAM,WAAW,CAAC;AAiB7B,KAAK,UAAU,eAAe,CAC5B,QAAgB;IAEhB,MAAM,KAAK,GAAG,IAAI,GAAG,EAAkB,CAAC;IACxC,KAAK,UAAU,IAAI,CACjB,UAAkB,EAClB,cAAsB;QAEtB,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;QACtE,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC5B,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;YACpD,MAAM,aAAa,GACjB,cAAc,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,cAAc,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC;YACzE,IAAI,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;gBACxB,MAAM,IAAI,CAAC,SAAS,EAAE,aAAa,CAAC,CAAC;YACvC,CAAC;iBAAM,IAAI,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC;gBAC1B,KAAK,CAAC,GAAG,CAAC,aAAa,EAAE,MAAM,EAAE,CAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,CAAC;YACjE,CAAC;QACH,CAAC;IACH,CAAC;IACD,MAAM,IAAI,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;IACzB,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,KAA8B,EAC9B,WAAmB;IAEnB,MAAM,WAAW,GAAG,MAAM,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC,CAAC;IAC5E,MAAM,kBAAkB,GAAG,MAAM,eAAe,CAC9C,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,OAAO,CAAC,CAChC,CAAC;IACF,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC,CAAC;IAE7D,MAAM,gBAAgB,GAAG,MAAM,CAAC,KAAK,CAAC;IAEtC,yDAAyD;IACzD,KAAK,MAAM,CAAC,YAAY,EAAE,eAAe,CAAC,IAAI,kBAAkB,EAAE,CAAC;QACjE,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,YAAY,CAAC,EAAE,CAAC;YACxC,MAAM,IAAI,KAAK,CACb,4DAA4D,YAAY,gBAAgB,KAAK,CAAC,EAAE,IAAI,CACrG,CAAC;QACJ,CAAC;QACD,MAAM,aAAa,GAAG,gBAAgB,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;QACzD,IAAI,aAAa,KAAK,eAAe,EAAE,CAAC;YACtC,MAAM,IAAI,KAAK,CACb,kDAAkD,YAAY,gBAAgB,KAAK,CAAC,EAAE,IAAI,CAC3F,CAAC;QACJ,CAAC;IACH,CAAC;IAED,oDAAoD;IACpD,KAAK,MAAM,YAAY,IAAI,gBAAgB,CAAC,IAAI,EAAE,EAAE,CAAC;QACnD,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,YAAY,CAAC,EAAE,CAAC;YAC1C,MAAM,IAAI,KAAK,CACb,sDAAsD,YAAY,wBAAwB,KAAK,CAAC,EAAE,IAAI,CACvG,CAAC;QACJ,CAAC;IACH,CAAC;AACH,CAAC"}