@dzhechkov/harness-core 0.3.150 → 0.4.2

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 (111) hide show
  1. package/.dz-manifest.json +410 -62
  2. package/README.md +81 -3
  3. package/dist/agentdb-index.d.ts.map +1 -1
  4. package/dist/agentdb-index.js +10 -2
  5. package/dist/agentdb-index.js.map +1 -1
  6. package/dist/backlog-embed.d.ts +94 -0
  7. package/dist/backlog-embed.d.ts.map +1 -0
  8. package/dist/backlog-embed.js +138 -0
  9. package/dist/backlog-embed.js.map +1 -0
  10. package/dist/backlog.d.ts +180 -7
  11. package/dist/backlog.d.ts.map +1 -1
  12. package/dist/backlog.js +429 -26
  13. package/dist/backlog.js.map +1 -1
  14. package/dist/challenge-panel.d.ts +3 -0
  15. package/dist/challenge-panel.d.ts.map +1 -1
  16. package/dist/challenge-panel.js +3 -0
  17. package/dist/challenge-panel.js.map +1 -1
  18. package/dist/export-holdout.d.ts +149 -0
  19. package/dist/export-holdout.d.ts.map +1 -0
  20. package/dist/export-holdout.js +198 -0
  21. package/dist/export-holdout.js.map +1 -0
  22. package/dist/feature-adr-checkpoints.d.ts +127 -0
  23. package/dist/feature-adr-checkpoints.d.ts.map +1 -1
  24. package/dist/feature-adr-checkpoints.js +199 -1
  25. package/dist/feature-adr-checkpoints.js.map +1 -1
  26. package/dist/feature-adr-routing.d.ts +3 -0
  27. package/dist/feature-adr-routing.d.ts.map +1 -1
  28. package/dist/feature-adr-routing.js +3 -0
  29. package/dist/feature-adr-routing.js.map +1 -1
  30. package/dist/guard.d.ts +42 -0
  31. package/dist/guard.d.ts.map +1 -1
  32. package/dist/guard.js +73 -1
  33. package/dist/guard.js.map +1 -1
  34. package/dist/index.d.ts +16 -3
  35. package/dist/index.d.ts.map +1 -1
  36. package/dist/index.js +28 -2
  37. package/dist/index.js.map +1 -1
  38. package/dist/loop-blobs.generated.d.ts +33 -0
  39. package/dist/loop-blobs.generated.d.ts.map +1 -0
  40. package/dist/loop-blobs.generated.js +101 -0
  41. package/dist/loop-blobs.generated.js.map +1 -0
  42. package/dist/loop-lint.d.ts +63 -0
  43. package/dist/loop-lint.d.ts.map +1 -0
  44. package/dist/loop-lint.js +606 -0
  45. package/dist/loop-lint.js.map +1 -0
  46. package/dist/loop-plan.d.ts +416 -0
  47. package/dist/loop-plan.d.ts.map +1 -0
  48. package/dist/loop-plan.js +1151 -0
  49. package/dist/loop-plan.js.map +1 -0
  50. package/dist/loop-render.d.ts +104 -0
  51. package/dist/loop-render.d.ts.map +1 -0
  52. package/dist/loop-render.js +1068 -0
  53. package/dist/loop-render.js.map +1 -0
  54. package/dist/loop-trace.d.ts +229 -0
  55. package/dist/loop-trace.d.ts.map +1 -0
  56. package/dist/loop-trace.js +614 -0
  57. package/dist/loop-trace.js.map +1 -0
  58. package/dist/mutation-gate.d.ts +247 -0
  59. package/dist/mutation-gate.d.ts.map +1 -0
  60. package/dist/mutation-gate.js +535 -0
  61. package/dist/mutation-gate.js.map +1 -0
  62. package/dist/no-stubs.d.ts +53 -0
  63. package/dist/no-stubs.d.ts.map +1 -0
  64. package/dist/no-stubs.js +190 -0
  65. package/dist/no-stubs.js.map +1 -0
  66. package/dist/package-skill-layouts.d.ts +67 -0
  67. package/dist/package-skill-layouts.d.ts.map +1 -0
  68. package/dist/package-skill-layouts.js +81 -0
  69. package/dist/package-skill-layouts.js.map +1 -0
  70. package/dist/patterns.d.ts.map +1 -1
  71. package/dist/patterns.js +156 -75
  72. package/dist/patterns.js.map +1 -1
  73. package/dist/recall-domain-boost.d.ts.map +1 -1
  74. package/dist/recall-domain-boost.js +6 -0
  75. package/dist/recall-domain-boost.js.map +1 -1
  76. package/dist/statusline.d.ts +10 -2
  77. package/dist/statusline.d.ts.map +1 -1
  78. package/dist/statusline.js +122 -36
  79. package/dist/statusline.js.map +1 -1
  80. package/dist/store-lock.d.ts +108 -0
  81. package/dist/store-lock.d.ts.map +1 -0
  82. package/dist/store-lock.js +231 -0
  83. package/dist/store-lock.js.map +1 -0
  84. package/dist/workflows.d.ts +16 -22
  85. package/dist/workflows.d.ts.map +1 -1
  86. package/dist/workflows.js +17 -98
  87. package/dist/workflows.js.map +1 -1
  88. package/package.json +6 -4
  89. package/sbom.json +1073 -203
  90. package/src/agentdb-index.ts +10 -1
  91. package/src/backlog-embed.ts +156 -0
  92. package/src/backlog.ts +536 -28
  93. package/src/challenge-panel.ts +4 -0
  94. package/src/export-holdout.ts +235 -0
  95. package/src/feature-adr-checkpoints.ts +291 -1
  96. package/src/feature-adr-routing.ts +4 -0
  97. package/src/guard.ts +106 -1
  98. package/src/index.ts +62 -2
  99. package/src/loop-blobs.generated.ts +114 -0
  100. package/src/loop-lint.ts +643 -0
  101. package/src/loop-plan.ts +1419 -0
  102. package/src/loop-render.ts +1126 -0
  103. package/src/loop-trace.ts +727 -0
  104. package/src/mutation-gate.ts +701 -0
  105. package/src/no-stubs.ts +204 -0
  106. package/src/package-skill-layouts.ts +107 -0
  107. package/src/patterns.ts +135 -60
  108. package/src/recall-domain-boost.ts +6 -0
  109. package/src/statusline.ts +117 -30
  110. package/src/store-lock.ts +258 -0
  111. package/src/workflows.ts +18 -117
@@ -0,0 +1,416 @@
1
+ /**
2
+ * `loop-plan/1` — the versioned, typed workflow-plan schema of the loop-designer meta-factory
3
+ * (feature loop-designer, ADR-001).
4
+ *
5
+ * ONE semantic source of truth (the plan) with THREE derived analytical projections (AM-3 /
6
+ * Codex 04/Q1's "one plan, three projections" correction):
7
+ * - `toOracleProjection` → graph-diff against a hand-authored, requirement-derived oracle;
8
+ * - `toLintProjection` → CFG with synthetic entry/exit + explicit fork/join pairs for
9
+ * `loop-lint.ts` (barrier post-dominance, budget, reachability);
10
+ * - `toTraceProjection` → expected runtime invariants for `loop-trace.ts::runInvariants`.
11
+ * No consumer reads `plan.steps`/`plan.deps`/… directly — enforced by the layer-1 source grep
12
+ * `loop-projection-consumers.test.ts` (empty allowlist).
13
+ *
14
+ * This schema deliberately carries NO LangGraph branding and adopts none of LangGraph's execution
15
+ * semantics (AM-7): it is an internally-versioned typed plan that names its own semantics —
16
+ * `RetryProfile.maxAttempts` INCLUDES the initial attempt (AM-4), retryable failure classes are a
17
+ * CLOSED serializable enum (never a callable), `cache` (keyed on normalized input) is a SEPARATE
18
+ * identity from `checkpointing` (keyed on execution position — INV-6).
19
+ *
20
+ * Extension point: any top-level or per-step key matching /^x-/ is accepted by `parsePlan`,
21
+ * preserved by `normalizePlan` in canonical order (so it participates in `planDigest`), and
22
+ * ignored by `validatePlan` and all three projections (narrowing N-2 — vendor/consumer data such
23
+ * as a cfr case-set rides as `x-caseSet` without schema surgery).
24
+ *
25
+ * Everything here is pure (node:crypto for the digest only — no fs, no clock, no randomness).
26
+ */
27
+ export declare const LOOP_PLAN_SCHEMA = "loop-plan/1";
28
+ /** Blob/schema version stamp read by scripts/gen-loop-blobs.mjs (this module is NOT a blob source
29
+ * today; the stamp keeps the convention uniform for every loop-designer module). */
30
+ export declare const LOOP_PLAN_MODULE_VERSION = "1.0.0";
31
+ export type StepKind = 'agent' | 'fanout' | 'join' | 'gate' | 'pause';
32
+ export type Deliverable = 'return-value' | 'file';
33
+ export type ConcurrencyShape = 'barrier' | 'pipeline';
34
+ export type DispatchRoute = 'inline' | 'codex-wrapper' | 'codex-exec';
35
+ /** CLOSED serializable failure-class enum (AM-4 — never a callable). */
36
+ export declare const RETRYABLE_FAILURE_CLASSES: readonly ["timeout", "transport", "malformed-output", "policy-refusal"];
37
+ export type FailureClass = (typeof RETRYABLE_FAILURE_CLASSES)[number];
38
+ /** The closed join-policy set (INV-3). `quorum:<n>` is validated by pattern. */
39
+ export declare const JOIN_POLICIES: readonly ["all-declared", "all-activated", "any"];
40
+ export declare const QUORUM_RE: RegExp;
41
+ /**
42
+ * Retry semantics owned by THIS schema (AM-4 — no verbatim LangGraph RetryPolicy copy):
43
+ * - `maxAttempts` INCLUDES the initial attempt: `1` = run once, never retry (the default for
44
+ * `kind:'agent'` steps — agent stages are expensive and rarely idempotent).
45
+ * - `retryableFailureClasses` is a CLOSED serializable enum list — a function value is a parse error.
46
+ *
47
+ * v1 NARROWING (QE round 6): the retry-TIMING family — `initialDelayMs` / `backoffMultiplier` /
48
+ * `maxDelayMs` / `jitter` — is NOT enacted by loop-plan/1 v1 and is VALIDATED-AWAY
49
+ * (`ENACT-RETRY-TIMING`). v1 retries are IMMEDIATE. Rationale: this field family reopened a
50
+ * reviewer blocker in every round it was "enacted" (round-4: the member projection dropped
51
+ * `initialDelayMs`; round-5: `backoffMultiplier`/`maxDelayMs` without `initialDelayMs` validated
52
+ * and vanished symmetrically; negative delays and a zero multiplier validated then were silently
53
+ * skipped). A plan must not validate while promising unperformed timing — see roadmap.
54
+ */
55
+ export interface RetryProfile {
56
+ /** Total attempt budget, INCLUDING the initial attempt (1 = no retry). */
57
+ maxAttempts: number;
58
+ /** NOT ENACTED in v1 — rejected by ENACT-RETRY-TIMING (retries are immediate); see roadmap. Milliseconds. */
59
+ initialDelayMs?: number;
60
+ /** NOT ENACTED in v1 — rejected by ENACT-RETRY-TIMING; see roadmap. */
61
+ backoffMultiplier?: number;
62
+ /** NOT ENACTED in v1 — rejected by ENACT-RETRY-TIMING; see roadmap. Milliseconds. */
63
+ maxDelayMs?: number;
64
+ /** NOT ENACTED in v1 — rejected by ENACT-RETRY-TIMING (the sandbox has no randomness); see roadmap. */
65
+ jitter?: 'none' | 'full' | 'deterministic';
66
+ /** CLOSED enum of retryable failure classes — never a callable (AM-4). */
67
+ retryableFailureClasses?: FailureClass[];
68
+ }
69
+ /**
70
+ * Cache policy — a SEPARATE identity from checkpointing (INV-6): cache is keyed on the step's
71
+ * NORMALIZED INPUT; a checkpoint is keyed on EXECUTION POSITION. A step may be cacheable only
72
+ * when `idempotent: true` and its deliverable has no external side effect.
73
+ */
74
+ export interface CachePolicy {
75
+ enabled: boolean;
76
+ /** The canonical cache-key composition (documented, fixed for schema/1). */
77
+ keyedOn: 'workflowVersion+stageVersion+normalizedInput+model+promptHash+toolSchemaHash+parameters+artifactHashes';
78
+ ttl?: string;
79
+ invalidateOn?: string[];
80
+ }
81
+ export interface LoopStep {
82
+ stepId: string;
83
+ title?: string;
84
+ kind: StepKind;
85
+ /** The phase this step reports under; `meta.phases` order must match first-reference order (INV-7). */
86
+ phase: string;
87
+ deps?: string[];
88
+ /** Prompt seed rendered into the GENERATED region (part of the exec fingerprint's prompt axis). */
89
+ prompt?: string;
90
+ artifacts?: {
91
+ reads?: string[];
92
+ writes?: string[];
93
+ };
94
+ /** For fanout members: barrier (all A, then all B) vs pipeline (per-item chains). */
95
+ concurrency?: ConcurrencyShape;
96
+ /** Model spec for this step (resolved by the model-resolver blob when set). */
97
+ model?: string | null;
98
+ /** What the step delivers: its return value, or a file written out-of-band. Default 'return-value'. */
99
+ deliverable?: Deliverable;
100
+ idempotent?: boolean;
101
+ retry?: RetryProfile;
102
+ /** Cacheable only when idempotent and side-effect-free (INV-6). */
103
+ cacheable?: boolean;
104
+ cache?: CachePolicy;
105
+ /** NOT ENACTED in v1 — rejected by ENACT-CKPT-OPT (per-step checkpoint granularity is deferred;
106
+ * `checkpointing.enabled` checkpoints EVERY top-level agent step). The field false-flipped the
107
+ * exec fingerprint in two review rounds; see roadmap. */
108
+ checkpoint?: boolean;
109
+ budget?: {
110
+ maxAgents: number;
111
+ };
112
+ /** Dispatch route. v1 NARROWING (QE round 6): only 'inline' is enacted — 'codex-wrapper' and
113
+ * 'codex-exec' are VALIDATED-AWAY (ENACT-DISPATCH). The fire-and-forget wrapper returns a stub
114
+ * that reads as a clean result, and codex-exec had no live-proven enactment here; see roadmap. */
115
+ dispatch?: DispatchRoute;
116
+ /** For kind:'pause' — which declared pause state this step returns. */
117
+ pauseState?: string;
118
+ /** Extension keys (x-…) are preserved and digested, never validated. */
119
+ [xKey: `x-${string}`]: unknown;
120
+ }
121
+ export interface LoopFanout {
122
+ /** The stepId of the kind:'fanout' step this config belongs to. */
123
+ stage: string;
124
+ /** The member registry the fanout draws from — REQUIRED (INV-2). */
125
+ registry: string[];
126
+ /** Hard concurrency bound — REQUIRED, >= 1 (INV-2; unbounded fanout is unrepresentable-invalid). */
127
+ maxFanout: number;
128
+ dedup?: boolean;
129
+ reasonRequired?: boolean;
130
+ /** Per-item step chain (pipeline shape) — stepIds run in sequence per member. */
131
+ chain?: string[];
132
+ }
133
+ export interface LoopJoin {
134
+ /** The stepId of the kind:'join' step. */
135
+ stage: string;
136
+ /** The fanout stage this join closes (INV-3: every parallel region names its join). */
137
+ forStage: string;
138
+ branchSchema?: {
139
+ caveats?: string[];
140
+ };
141
+ /** From the closed set: all-declared | all-activated | any | quorum:<n>. */
142
+ joinPolicy: string;
143
+ onInvalid?: string;
144
+ }
145
+ export interface LoopGate {
146
+ stepId: string;
147
+ kind: string;
148
+ failRoute?: string;
149
+ maxRedos?: number;
150
+ }
151
+ export interface LoopPause {
152
+ /** Typed pause state name (checkpoint-return/re-invoke — never a generic interrupt, C-4). */
153
+ state: string;
154
+ payloadSchema?: Record<string, unknown>;
155
+ /** The args key a re-invoke supplies to resume past this pause. */
156
+ resumeArg: string;
157
+ }
158
+ /** The 5 explicit opt-in subsystem booleans — default ALL false. `model-resolver` is NOT an
159
+ * opt-in: it auto-includes whenever any `step.model` is set (DDD resolution, 04 §3.1). */
160
+ export interface LoopSubsystems {
161
+ checkpoints?: boolean;
162
+ /** Default OFF — the health-advisor PHI lesson (AM-9): capture is never on by default. */
163
+ trainingPairs?: boolean;
164
+ usageAdaptive?: boolean;
165
+ challengePanel?: boolean;
166
+ /** NOT ENACTED in v1 — enabling it is rejected (ENACT-SUBSYS): codex dispatch routes are
167
+ * validated-away (ENACT-DISPATCH), so the subsystem blob would inject with no call sites. */
168
+ codexDispatch?: boolean;
169
+ }
170
+ export interface LoopPlan {
171
+ schema: typeof LOOP_PLAN_SCHEMA;
172
+ name: string;
173
+ description: string;
174
+ whenToUse: string;
175
+ steps: LoopStep[];
176
+ gates?: LoopGate[];
177
+ fanouts?: LoopFanout[];
178
+ joins?: LoopJoin[];
179
+ pauses?: LoopPause[];
180
+ /** `schemaVersion` is NOT ENACTED in v1 — rejected by ENACT-CKPT-OPT (v1 pins `loop-ckpt-1`);
181
+ * the declared-vs-default distinction false-flipped the fingerprint in round 3; see roadmap. */
182
+ checkpointing?: {
183
+ enabled: boolean;
184
+ schemaVersion?: string;
185
+ };
186
+ subsystems?: LoopSubsystems;
187
+ trace?: {
188
+ emit: boolean;
189
+ };
190
+ [xKey: `x-${string}`]: unknown;
191
+ }
192
+ export interface ParseError {
193
+ path: string;
194
+ message: string;
195
+ }
196
+ export interface Diagnostic {
197
+ invariant: string;
198
+ path: string;
199
+ message: string;
200
+ }
201
+ /**
202
+ * THE ItemKey domain — ONE regex object, shared by the PLAN layer (`fanouts[].registry` items) and
203
+ * the TRACE layer (`loop-trace.ts`'s dispatch-event `itemKey`/`stepId` VO check). It is the SAME
204
+ * object, not a copy: `ITEM_KEY_RE === TRACE_KEY_RE` is asserted by test, so the two layers can
205
+ * never drift apart.
206
+ *
207
+ * QE round-7 (Codex round-6 R2/R3, MEASURED): `registry: ["hello world"]` parsed and validated
208
+ * with ZERO findings — INV-2 checked only that the registry was a non-empty string array — and the
209
+ * run then behaved DIFFERENTLY depending on a field that is supposed to be observational only:
210
+ * with `trace.emit:false` it COMPLETED with one member call; with `trace.emit:true` it died BEFORE
211
+ * the member call with `loop-trace: refusing non-conforming event (itemKey fails its VO regex)`.
212
+ * A declared, retained field whose plan-domain and runtime-domain disagree is exactly the "a valid
213
+ * plan promises what the runtime will not perform" class; the domain is now ONE, checked at parse.
214
+ */
215
+ export declare const ITEM_KEY_RE: RegExp;
216
+ /** The ItemKey validator both layers use (the plan half; the trace half calls the same regex). */
217
+ export declare function isItemKey(v: unknown): v is string;
218
+ /**
219
+ * COLLISION-RESISTANT stepId → JS-identifier lowering, with parse-time collision rejection by
220
+ * IDENT-1 (QE round-6; the round-5 reviewer's named third class: `a-b` and `a.b` both lowered to
221
+ * `a_b`, so two LEGAL distinct stepIds rendered `SyntaxError: Identifier 'USER_PROMPT_a_b' has
222
+ * already been declared`). A lossless id (already a pure `[A-Za-z0-9_]` word) lowers to itself; a
223
+ * LOSSY sanitization always appends an 8-hex sha256 suffix of the ORIGINAL id, so two distinct ids
224
+ * no longer collide by ACCIDENT. The IDENT-1 parse check is the belt — both for crafted names that
225
+ * imitate the suffix form and for the (astronomically unlikely by accident, cheap for an attacker)
226
+ * truncated-hash collision. This function is NOT injective; see the honesty note below.
227
+ *
228
+ * HONESTY NOTE (QE round-7 — the round-6 reviewer's caveat, CONCEDED verbatim: "an 8-hex truncated
229
+ * hash is not itself mathematically injective; the parse belt supplies the actual safety"). A
230
+ * 32-bit truncation of sha256 is COLLISION-RESISTANT, not INJECTIVE: over a 32-bit codomain,
231
+ * distinct originals with the same sanitized stem CAN in principle share a suffix (finding such a
232
+ * pair costs ~2^16 tries by the birthday bound — cheap for an ATTACKER, unreachable by accident).
233
+ * So the guarantee this function carries alone is "no ACCIDENTAL collision"; the guarantee that a
234
+ * plan with two ids lowering to one identifier is REJECTED is IDENT-1's (parsePlan), which
235
+ * compares the ACTUAL lowered strings and needs no injectivity assumption. IDENT-1 is the safety
236
+ * belt; widening the suffix would only move the bound, never remove the need for the belt.
237
+ */
238
+ export declare function stepIdent(stepId: string): string;
239
+ export type FieldDomain = {
240
+ t: 'bespoke';
241
+ } | {
242
+ t: 'string';
243
+ } | {
244
+ t: 'boolean';
245
+ } | {
246
+ t: 'number';
247
+ } | {
248
+ t: 'posInt';
249
+ } | {
250
+ t: 'enum';
251
+ values: readonly string[];
252
+ } | {
253
+ t: 'string[]';
254
+ } | {
255
+ t: 'record';
256
+ } | {
257
+ t: 'record[]';
258
+ } | {
259
+ t: 'string|null';
260
+ };
261
+ /** Keys are `<Interface>.<field>` plus `<inlineField>.<sub>` — EXACTLY the keys the honesty test
262
+ * extracts from this file's interface source (both directions asserted there). */
263
+ export declare const FIELD_DOMAINS: Record<string, FieldDomain>;
264
+ /** `<iface>` → its accepted field names, derived from FIELD_DOMAINS (never hand-written). */
265
+ export declare const KNOWN_KEYS: Record<string, ReadonlySet<string>>;
266
+ /** The record kinds that carry the documented `[xKey: \`x-${string}\`]` vendor escape — i.e. the
267
+ * ONLY scopes where an `x-` key is accepted (Codex round-6: "Restrict `x-` acceptance to its
268
+ * documented scopes"). The honesty test derives this set from the interface SOURCE (which
269
+ * interfaces declare the index signature) in both directions, so it cannot drift either. */
270
+ export declare const X_KEY_IFACES: ReadonlySet<string>;
271
+ /**
272
+ * REQUIRED fields per record kind (QE round-6; Codex round-5 R1 blocker 1: a `fanouts[]` record
273
+ * with the REQUIRED `stage` field ABSENT parsed, validated, and rendered a zero-agent COMPLETED
274
+ * run — `parsePlan` checked only PRESENT fields and XREF-1 skipped `undefined` targets).
275
+ * Same discipline as FIELD_DOMAINS: the table is TOTAL over the schema's record kinds, and the
276
+ * honesty test derives the expected sets from the interface SOURCE (fields declared without `?`),
277
+ * so a new required field cannot ship unenforced and a stale entry cannot linger.
278
+ *
279
+ * Keys marked in OWNED_ABSENCE have dedicated absence diagnostics in parsePlan (kept verbatim for
280
+ * message stability); the REQUIRED pass enforces everything else.
281
+ */
282
+ export declare const REQUIRED_FIELDS: Record<string, readonly string[]>;
283
+ export declare const STEP_FIELD_KINDS: Record<string, readonly StepKind[]>;
284
+ export interface CrossRef {
285
+ /** '<collection>[].<field>' — the referencing field, as documented in diagnostics. */
286
+ ref: string;
287
+ /** Legal target step kinds. A reference to an existing step of another kind is XREF-1. */
288
+ targetKinds: readonly StepKind[];
289
+ /** 'terminal:<name>' allowed in place of a stepId (gate terminal routes). */
290
+ allowTerminal?: true;
291
+ /** How the renderer CONSUMES an accepted record (doc — the UNCONSUMED-1 checks assert the
292
+ * reverse direction where a skip/no-op is otherwise possible). */
293
+ consumes: string;
294
+ /** Enumerate every reference instance this field carries in a plan (the table is self-contained:
295
+ * a new entry cannot ship without its accessor, so it cannot silently validate nothing). */
296
+ get: (plan: LoopPlan) => {
297
+ target: string | undefined;
298
+ path: string;
299
+ }[];
300
+ }
301
+ export declare const CROSS_REFS: readonly CrossRef[];
302
+ /**
303
+ * Parse a raw JSON value into a LoopPlan, or return the ParseError list (union return per the
304
+ * behavioral contract). Structural only — semantic invariants live in `validatePlan`.
305
+ * `x-` keys at the top level and per step are accepted and carried through verbatim.
306
+ * A callable/`function` value anywhere in a retry field is a PARSE error (AM-4).
307
+ */
308
+ export declare function parsePlan(json: unknown): LoopPlan | ParseError[];
309
+ /** True when a parsePlan return is the error branch of the union. */
310
+ export declare function isParseErrors(v: LoopPlan | ParseError[]): v is ParseError[];
311
+ /**
312
+ * Semantic validation — INV-1…8 (one diagnostic per violated invariant instance, each naming the
313
+ * invariant it defends). Pure; never throws.
314
+ */
315
+ export declare function validatePlan(plan: LoopPlan): Diagnostic[];
316
+ /**
317
+ * Canonical form: object keys sorted (x- keys included, so they participate in the digest),
318
+ * cosmetic fields stripped, undefined dropped, step/array ORDER preserved (order is semantic —
319
+ * INV-7 phase order derives from it).
320
+ */
321
+ export declare function normalizePlan(plan: LoopPlan): LoopPlan;
322
+ /** sha256 over the canonical JSON of the normalized plan. */
323
+ export declare function planDigest(plan: LoopPlan): string;
324
+ export interface OracleProjection {
325
+ kind: 'oracle-projection/1';
326
+ steps: {
327
+ id: string;
328
+ kind: StepKind;
329
+ phase: string;
330
+ }[];
331
+ transitions: {
332
+ from: string;
333
+ to: string;
334
+ kind: 'dep';
335
+ }[];
336
+ regions: {
337
+ fanout: string;
338
+ join: string;
339
+ joinPolicy: string;
340
+ maxFanout: number;
341
+ registry: string[];
342
+ chain: string[];
343
+ }[];
344
+ }
345
+ /** Normalized logical graph for the oracle diff: steps + typed transitions + region membership,
346
+ * canonical (sorted) ordering, cosmetic fields gone. */
347
+ export declare function toOracleProjection(plan: LoopPlan): OracleProjection;
348
+ export interface LintProjection {
349
+ kind: 'lint-projection/1';
350
+ /** CFG nodes: synthetic 'entry'/'exit' + every stepId. */
351
+ nodes: string[];
352
+ /** Directed edges entry→roots, dep edges, leaves→exit. */
353
+ edges: {
354
+ from: string;
355
+ to: string;
356
+ }[];
357
+ /** Explicit fork/join pairs with the branches activated between them. */
358
+ forkJoinPairs: {
359
+ fork: string;
360
+ join: string;
361
+ policy: string;
362
+ branches: string[];
363
+ maxFanout: number;
364
+ registrySize: number;
365
+ }[];
366
+ /** Phase first-reference order (INV-7 cross-check). */
367
+ phaseOrder: string[];
368
+ /** Per-step lint facts (budget, retry, dispatch, deliverable, cache) — the rule inputs. */
369
+ facts: {
370
+ id: string;
371
+ kind: StepKind;
372
+ budgetMaxAgents: number | null;
373
+ maxAttempts: number;
374
+ idempotent: boolean;
375
+ deliverable: Deliverable;
376
+ dispatch: DispatchRoute;
377
+ cacheable: boolean;
378
+ writes: string[];
379
+ }[];
380
+ pauses: {
381
+ state: string;
382
+ resumeArg: string;
383
+ }[];
384
+ checkpointingEnabled: boolean;
385
+ traceEmit: boolean;
386
+ }
387
+ /** Control-flow/dependency graph with synthetic entry/exit and explicit fork/join pairs —
388
+ * the ONLY plan view `loop-lint.ts` consumes. */
389
+ export declare function toLintProjection(plan: LoopPlan): LintProjection;
390
+ export interface TraceProjection {
391
+ kind: 'trace-projection/1';
392
+ /** Expected happens-before edges: every dispatch of `step` must come after the settle of each
393
+ * dep. Only DISPATCHING step kinds (agent/gate) appear — fanout/join/pause are structural
394
+ * pseudo-steps that emit no trace events of their own (their ordering lives in `regions`). */
395
+ happensBefore: {
396
+ step: string;
397
+ afterSettleOf: string;
398
+ }[];
399
+ /** Parallel regions with the runtime bound + concurrency shape the trace must exhibit.
400
+ * `after` = the dispatching steps that depend on the region (fanout or join) — the trace-visible
401
+ * witnesses of the barrier. */
402
+ regions: {
403
+ fanout: string;
404
+ join: string;
405
+ joinPolicy: string;
406
+ maxFanout: number;
407
+ members: string[];
408
+ shape: ConcurrencyShape;
409
+ after: string[];
410
+ }[];
411
+ /** Steps expected to appear in the trace, keyed by stepId (iteration/attempt keys are runtime axes). */
412
+ expectedSteps: string[];
413
+ }
414
+ /** Expected runtime invariants — the ONLY plan view `loop-trace.ts::runInvariants` consumes. */
415
+ export declare function toTraceProjection(plan: LoopPlan): TraceProjection;
416
+ //# sourceMappingURL=loop-plan.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"loop-plan.d.ts","sourceRoot":"","sources":["../src/loop-plan.ts"],"names":[],"mappings":"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"}