Merge remote-tracking branch 'origin/main' into claude/issue-15478-stale-repository-directory

Author: claude

.changeset/stack-cross-reference-refusal-envelope.md

@@ -0,0 +1,16 @@
+---
+"@objectstack/spec": patch
+"@objectstack/runtime": patch
+---
+
+fix(spec): `defineStack`'s cross-reference refusal carries an ADR-0112 envelope, so the five REFUSED ADR-0130 item classes are machine-readable (#14552)
+
+`validateCrossReferences` — reached through `defineStack` — refuses a stack whose items name an object the stack does not define. That refusal was `new Error(message)` with `code` and `status` both `undefined`, so all five REFUSED item classes of the ADR-0130 matrix (action `objectName`, view `data.object`, permission-set `objects`, seed dataset `object`, import mapping `targetObject`) plus the `hooks[].object` rule (#14122 §4 rule R4) were distinguishable only by MESSAGE TEXT. It now throws `StackCrossReferenceError`, carrying `code: 'STACK_CROSS_REFERENCE_INVALID'`, `status: 422`, and one entry per finding in `issues`. The message text is byte-for-byte unchanged: this adds fields rather than rewriting a sentence, and five message-substring pins in the tree read that prose.
+
+ADR-0112 makes `code` / `status` the machine-readable half of every refusal. Without them `os validate`, `os build` and any AI author reading the refusal could only pattern-match prose — the fragile shape the envelope exists to remove, made worse here because the message had already become load-bearing for those pins.
+
+Why ONE code rather than five: there is exactly one raise site. `validateCrossReferences` returns every finding as a `string[]` and `defineStack` throws the collected set at once, so a single refusal can carry findings from several classes together and a per-class code would have to pick one of several true answers. The classes stay machine-readable in `issues`. The family is also wider than "undefined object" — the same aggregate carries the duplicate-action-key, global-`update`-action and mapping `javascript`-transform findings — so a `…_UNDEFINED_OBJECT` spelling would have been false for those.
+
+Not narrowed, not widened: no accept-set changes and no export changes. `defineStack` accepts and refuses exactly the inputs it did before, and `StackCrossReferenceError` is deliberately module-local — `packages/spec/src/index.ts` re-exports that module with `export *`, so exporting the class would widen the published api-surface of the contract package, and the ADR-0112 contract is the `code` / `status` fields, which every reader reads structurally rather than by `instanceof`. No ledger registration either, for the same reason its two precedents (`ObjectOwnershipConflictError` #14367, `NamespaceConflictError` #14474) carry none: no wire door raises it. `defineStack` runs at authoring and boot time, and no HTTP domain handler calls it.
+
+`@objectstack/runtime` carries the classification row for the new code in the dispatcher error-code vocabulary (verdict `boot-refusal`, door `none` — the measured verdict, not the expected one).

.changeset/subflow-bubble-stranded-parent.md

@@ -0,0 +1,35 @@
+---
+'@objectstack/service-automation': patch
+---
+
+automation: a subflow parent left STRANDED by a failed up-bubble is reported at `error`, not `warn`
+
+When an approval (or any pause) sits inside a subflow child, resuming the child
+bubbles up to the parent. If the parent's own continuation then fails on the
+engine's stranded exit — its suspension consumed, a repair snapshot journalled,
+the run recorded `failed` — nothing but a `warn` said so, while the child's
+resumer (an approvals decision door, a wait timer) was told the resume
+succeeded. Persisted state and runtime state disagree and nothing looks broken
+from the outside, which is the durability class.
+
+`bubbleToParent` now grades that record by the engine's own
+`AutomationResult.status` discriminator: `'stranded'` is reported at `error`,
+naming the parent run and the `restoreConsumedSuspension` verb that repairs it.
+Every other parent-resume failure — a concurrent resume, an unreachable store,
+a thrown resume — stays at `warn` unchanged, on a narrower ground: those exits
+carry no `'stranded'` discriminator. `'stranded'` is the one exit that journals
+a repair snapshot, so it is the one an operator can act on, and grading by the
+engine's own verdict is what keeps `error` readable.
+
+⚠️ That is a statement about what this seam can KNOW, not a guarantee that
+every other exit left the parent healthy. Two exits are known not to be:
+
+- a **thrown** parent resume carries no discriminator at all, and #15555
+  documents a window in which a throw between the journal and the stamp hides a
+  parent that IS stranded. Left at `warn` deliberately, for that card;
+- the **claim-path** store failure reports, in its own envelope text, that
+  whether the suspension was consumed is UNKNOWN — it relies on a retry to
+  settle it, and an up-bubble has no retrier. ("Not consumed" is the guarantee
+  of the strict-load store failure only, not of every store failure.)
+
+⚠️ This is the log half only. What the child's resumer is told is unchanged.

packages/objectql/src/registry-cross-package-item-classes.test.ts

@@ -35,19 +35,24 @@
  * both, and the matrix's verdict is the EFFECTIVE one — refused at authoring
  * means the module cannot be written, whatever the registry would have done.
  *
- * ## ⚠️ The authoring gate throws a BARE `Error` — there is no ADR-0112 envelope
+ * ## ✅ The authoring gate carries an ADR-0112 envelope (#14552)
  *
- * `defineStack` aggregates its cross-reference errors into `new Error(...)`.
- * There is no `code` and no `status` to assert, so these rows assert the
- * message — which IS the contract here, since the message is the only thing
- * that distinguishes one refusal from another — and then assert the ABSENCE of
- * the envelope explicitly, in one place, so the gap is pinned rather than
- * merely unmentioned. Same shape of gap as #14367 (`registerObject`'s bare
- * `Error`), one door over.
+ * `defineStack` aggregates its cross-reference errors and — since #14552 —
+ * raises them as `StackCrossReferenceError`: `code:
+ * 'STACK_CROSS_REFERENCE_INVALID'`, `status: 422`, one entry per finding in
+ * `issues`, with the message text byte-for-byte unchanged. The rows below
+ * still assert the MESSAGE, because the message is what distinguishes one item
+ * class from another (the code names the rule FAMILY — there is one raise site
+ * for all of them, and a single refusal can carry findings from several
+ * classes at once). `ENVELOPE PRESENCE` then asserts the envelope itself, in
+ * one place. Repaired the same way as #14367 (`registerObject`'s bare `Error`)
+ * and #14474 (`NamespaceConflictError`), one door over.
  *
- * ⛔ If `ENVELOPE ABSENCE` below goes red, an envelope has ARRIVED. That is an
- * improvement: update this pin and the #14122 §4 matrix row. Do not delete the
- * assertion to make it green.
+ * ⛔ If `ENVELOPE PRESENCE` below goes red, the envelope has been REMOVED or
+ * its code renamed — a regression, not a cleanup. Restore it rather than
+ * relaxing the assertion; five message-substring pins in this tree read the
+ * prose it fences, and the #14122 §4 matrix row records the envelope as
+ * present.
  *
  * ## This file measures. It does not prescribe.
  *
@@ -248,14 +253,17 @@ describe('#14122 §4 continuity — the method reproduces an already-measured ru
     expect(authoringVerdict(hookItem, true)).toBeUndefined();
   });
 
-  it('ENVELOPE ABSENCE — the authoring gate carries no ADR-0112 `code` / `status`', () => {
+  it('ENVELOPE PRESENCE — the authoring gate carries the ADR-0112 `code` / `status` (#14552)', () => {
     // Pinned once, here, rather than repeated on every refusing row. See the
-    // file header: red here means an envelope ARRIVED (good) — update the pin
-    // and the §4 matrix, do not delete the assertion.
+    // file header: red here means the envelope was REMOVED or renamed — a
+    // regression. Restore it, do not relax the assertion.
     const refused = authoringVerdict(hookItem);
     expect(refused).toBeInstanceOf(Error);
-    expect(refused?.code).toBeUndefined();
-    expect(refused?.status).toBeUndefined();
+    expect(refused?.code).toBe('STACK_CROSS_REFERENCE_INVALID');
+    expect(refused?.status).toBe(422);
+    // The message text is unchanged by the envelope — this pin fences both
+    // halves at once, which is what makes it a regression detector for the
+    // five message-substring pins elsewhere in the tree.
     expect(refused?.message).toContain('defineStack cross-reference validation failed');
   });
 });