@objectstack/types 17.3.0 → 17.4.0

package/CHANGELOG.md

@@ -1,5 +1,170 @@
 # @objectstack/types
 
+## 17.4.0
+
+### Minor Changes
+
+- 3d3f60e: An approval decision that lands while its flow run strands now says so in fields, not only in prose.
+  
+  `POST /api/v1/approvals/requests/{id}/reject` — and its sibling decision doors — could produce three coexisting outcomes from one call: the caller read HTTP 500, the request row **was** in its terminal status and had left the pending inbox, and the workflow run was stranded. A caller reading 500 has one honest inference available — "the rejection did not happen" — and it was the wrong one, so scripts and operators retried or escalated against a decision that was already durable. The only carrier of the truth was English prose in `error`, so finding the affected run meant regexing a run id out of a sentence, and nothing said whether that run could be repaired at all.
+  
+  The 500 stays. A recorded decision whose flow never advances is still a failure and is still reported as one; the door does not become atomic and no decision is ever rolled back. What changed is that it stops discarding what the engine already said:
+  
+  - **The `RESUME_FAILED` body gains four fields**, additively — `finalized` (always `true`: the decision stands), `decision`, `runId`, and `repairable`. Existing consumers see the same `code`, the same `error` and the same status.
+  - **`repairable` carries the engine's own discriminator** — `AutomationResult.status === 'stranded'`, the state stamped on exactly the exit that journals a repair snapshot. `false` is the answer for every other failure, including a lost run: absence of the signal is not repairability, and a repair verb that would refuse is worse than no promise.
+  - **`serviceResume` carries `status`** through to the door. It previously read only `success` / `code` / `error`, and the stranded exit reports a `status` and no `code` at all — so the platform's own repairability signal died one line before the envelope was built.
+  
+  `@objectstack/types` gains `strandedDecisionFailure` / `strandedDecisionDetails` and the `StrandedDecisionDetails` type — the constructor and its recogniser in one module, so the producing service and the REST door cannot drift. A `RESUME_FAILED` raised without that carrier answers exactly the body it always did; the door never synthesises the envelope.
+
+### Patch Changes
+
+- 088f761: `createHostImporter` now loads the `import` build of an ALIASED dual-published package, instead of silently keeping its `require` build.
+  
+  An alias declaration — `{"dependencies": {"foo": "npm:bar@1"}}` — installs a package whose manifest is named `bar` under the key `foo`. On the path where CommonJS resolution SUCCEEDS, the importer re-decides only the CONDITION (it asks the package which entry an `import()` gets, so the caller's ESM chain and this load share one instance). That re-decision recognised the package root by walking up from the resolved entry until it found a manifest named after the DECLARATION KEY — `foo` — while an aliased install's manifest is named `bar`. The walk therefore never matched, the re-decision produced nothing, and the load fell back to whatever the CommonJS resolver had answered: the `require` condition.
+  
+  For an aliased dual publish that left the process holding two live copies of one package — the CommonJS build behind the host importer, the `import` build in the caller's own chain — which is exactly the split the condition re-decision exists to remove: a plugin registry, a singleton kernel, a module-level cache, one copy each.
+  
+  The expectation now comes from the host's own declaration (`npm:name@range`, aliased `workspace:name@range`), the same reading the ESM-only fallback finder has used since it learned about aliases. Nothing about the check's strictness moves: an alias naming one package still does not license a directory holding another, and a non-aliased declaration is still verified against its key. Declarations that name a LOCATION rather than a package (`link:`, `file:`) carry no name to expect, so they keep today's behaviour unchanged.
+  
+  Measured population for the behaviour change: zero aliased declarations exist across this workspace's 875 dependency declarations, and 867 of 867 installed declarations already match their key — no ordinary, non-aliased install reaches this path.
+- c5d6803: Published `.js.map` files no longer embed the complete original source text (`sourcesContent`) — comments included. `sourcemap: true` was esbuild shorthand, and esbuild's own default for `sourcesContent` is `true`; nobody had decided to publish every package's full source (including `@internal`/test-only comments) to npm inside its source maps, it fell out of a default nobody had looked at. Measured before this change: 55 of 57 publishable packages shipped embedded source text, and maps were roughly half of `@objectstack/spec`'s published bytes.
+  
+  `sourcesContent: false` is now set at one shared place (`scripts/tsup-drop-sources-content.mjs`, wired into every `tsup.config.ts` via tsup's `esbuildOptions` hook — most packages build through the repo-root config directly and pick this up with no config change of their own). `mappings` are untouched, so stack-trace positions still resolve correctly to the original file/line/column; only the embedded source text is gone.
+  
+  `@objectstack/cli` (built with `tsc`, not `tsup`) never embedded source text to begin with — its maps' `sources` entries point at `src/**` paths that are not part of the published tarball either way. That is not a defect unique to `cli`: every `tsup`-built package's `sources` entries are `../src/**`-relative paths that are equally outside `files: ["dist", …]`, and were merely masked by the embedded content that just stopped shipping. Shipping `src/**` in `files[]` to make `sources` resolve was rejected — it would put most of the removed bytes straight back. So `cli`'s maps are left exactly as `tsc` emits them: this is now the fleet-consistent shape (accurate `mappings`, non-resolving-but-honest `sources` labels, no embedded text), not an outlier.
+  
+  A new gate, `pnpm check:sourcemap-no-sources-content`, sweeps every built, non-private package's `dist/**/*.map` and fails if any of them carries a non-empty `sourcesContent` array — so a future `tsup.config.ts` that skips the shared hook, or a toolchain upgrade that changes esbuild's default back, is caught rather than silently re-publishing source text.
+- Updated dependencies [fe0d9a4]
+- Updated dependencies [ecd2158]
+- Updated dependencies [f2b5e46]
+- Updated dependencies [ed7243d]
+- Updated dependencies [6ba0db4]
+- Updated dependencies [625b0c3]
+- Updated dependencies [233222e]
+- Updated dependencies [07f40e5]
+- Updated dependencies [ceb4877]
+- Updated dependencies [e9fcd6b]
+- Updated dependencies [90e7e6d]
+- Updated dependencies [2bdabe6]
+- Updated dependencies [ca326b5]
+- Updated dependencies [8f404a5]
+- Updated dependencies [68437d4]
+- Updated dependencies [abb140c]
+- Updated dependencies [8333a6c]
+- Updated dependencies [3e3ecb0]
+- Updated dependencies [3030369]
+- Updated dependencies [d5d8d50]
+- Updated dependencies [e08892d]
+- Updated dependencies [ae05f2e]
+- Updated dependencies [b548e43]
+- Updated dependencies [c463d03]
+- Updated dependencies [64bd6a3]
+- Updated dependencies [13c48c2]
+- Updated dependencies [132742f]
+- Updated dependencies [85a2459]
+- Updated dependencies [50dc214]
+- Updated dependencies [e89fa92]
+- Updated dependencies [e9fcd6b]
+- Updated dependencies [8976ea1]
+- Updated dependencies [56fe8c2]
+- Updated dependencies [acabd24]
+- Updated dependencies [ab50c8f]
+- Updated dependencies [6491463]
+- Updated dependencies [89cf4d6]
+- Updated dependencies [21c5dcb]
+- Updated dependencies [6d4d5d3]
+- Updated dependencies [ed5d557]
+- Updated dependencies [bca21f7]
+- Updated dependencies [e9fcd6b]
+- Updated dependencies [1a7a7c9]
+- Updated dependencies [e9fcd6b]
+- Updated dependencies [ef3a138]
+- Updated dependencies [68d5dfd]
+- Updated dependencies [3e21cf0]
+- Updated dependencies [4cfc93b]
+- Updated dependencies [efd6b43]
+- Updated dependencies [859ded3]
+- Updated dependencies [fa125f3]
+- Updated dependencies [74628d9]
+- Updated dependencies [a646120]
+- Updated dependencies [6f1ce7d]
+- Updated dependencies [7778115]
+- Updated dependencies [2c753fe]
+- Updated dependencies [52804cd]
+- Updated dependencies [3f89967]
+- Updated dependencies [53cf263]
+- Updated dependencies [21aabbc]
+- Updated dependencies [9c270bb]
+- Updated dependencies [76c8c5a]
+- Updated dependencies [a84e1ce]
+- Updated dependencies [bf1054a]
+- Updated dependencies [d8d2776]
+- Updated dependencies [222dc0f]
+- Updated dependencies [e9fcd6b]
+- Updated dependencies [32c917d]
+- Updated dependencies [f9a3c32]
+- Updated dependencies [f502898]
+- Updated dependencies [af7edfe]
+- Updated dependencies [b60f48b]
+- Updated dependencies [c78c918]
+- Updated dependencies [cf9bda4]
+- Updated dependencies [784cb92]
+- Updated dependencies [7629f4d]
+- Updated dependencies [51df9fd]
+- Updated dependencies [a7da4de]
+- Updated dependencies [de0bcdd]
+- Updated dependencies [70f7d6d]
+- Updated dependencies [c677cda]
+- Updated dependencies [554a160]
+- Updated dependencies [f7da71e]
+- Updated dependencies [7f745c3]
+- Updated dependencies [5eb24f8]
+- Updated dependencies [2a3decc]
+- Updated dependencies [cc00df2]
+- Updated dependencies [f4e6adf]
+- Updated dependencies [ee4a59b]
+- Updated dependencies [4db3c61]
+- Updated dependencies [5ca314a]
+- Updated dependencies [e0af1a8]
+- Updated dependencies [414c1fc]
+- Updated dependencies [22c0279]
+- Updated dependencies [0db2947]
+- Updated dependencies [92b5d7f]
+- Updated dependencies [613bfbd]
+- Updated dependencies [abae16a]
+- Updated dependencies [094b8fd]
+- Updated dependencies [c7aca0d]
+- Updated dependencies [c1d8f98]
+- Updated dependencies [8e0b297]
+- Updated dependencies [5f7fa1d]
+- Updated dependencies [87f0ccc]
+- Updated dependencies [aedbaef]
+- Updated dependencies [c5d6803]
+- Updated dependencies [10d05bb]
+- Updated dependencies [69602e5]
+- Updated dependencies [c3ce76c]
+- Updated dependencies [7936b29]
+- Updated dependencies [46803fa]
+- Updated dependencies [c2a336c]
+- Updated dependencies [9f890d3]
+- Updated dependencies [0bb2318]
+- Updated dependencies [f7db8f4]
+- Updated dependencies [1ecee3e]
+- Updated dependencies [9408b7f]
+- Updated dependencies [e9fcd6b]
+- Updated dependencies [9bcd9be]
+- Updated dependencies [b398ad2]
+- Updated dependencies [99261a7]
+- Updated dependencies [81b426f]
+- Updated dependencies [001af1c]
+- Updated dependencies [fb77aa5]
+- Updated dependencies [581d8f8]
+- Updated dependencies [f81afe3]
+- Updated dependencies [40a44b9]
+- Updated dependencies [7a7fb03]
+- Updated dependencies [8fd246d]
+  - @objectstack/spec@17.4.0
+
 ## 17.3.0
 
 ### Minor Changes

package/dist/index.d.mts

@@ -475,8 +475,10 @@ declare function _resetEnvDeprecationWarnings(): void;
  * "Do not ship driver internals to clients" is a property of the HTTP
  * boundary, not of one router, so the predicate lives here — the package both
  * `@objectstack/rest` and `@objectstack/runtime` already depend on — and each
- * boundary applies it in its own envelope. One heuristic, one place to widen
- * when a new dialect's phrasing shows up.
+ * boundary applies it in its own envelope. One heuristic, one place — and
+ * since #16019 a FROZEN one: a phrasing it does not recognise is closed by the
+ * producer declaring its fault, never by a new row here (the ruling is
+ * recorded on {@link DIALECT_LEAK_PHRASINGS}).
  *
  * Deliberately a *heuristic over the message*, not a driver taxonomy: these
  * errors arrive as plain `Error`s from a half-dozen dialects with no shared
@@ -1340,6 +1342,118 @@ declare function fieldsFromZodIssues(issues: Array<{
     message: string;
 }>;
 
+/**
+ * The machine-readable half of a `RESUME_FAILED` — a decision that is durably
+ * recorded whose flow run could not be resumed (#13807).
+ *
+ * ## The condition
+ *
+ * An approval decision finalises: the `sys_approval_request` row flips to its
+ * terminal status, the audit action is written, the record's mirrored status
+ * field advances — and only THEN is the owning flow run resumed. When that
+ * resume fails the writes are already durable, so the outcome stands and the
+ * run is stranded. `@objectstack/plugin-approvals` throws rather than
+ * answering `resumed: false`, deliberately: a recorded decision whose flow
+ * never advances is #4420's zombie half-state, and the contract
+ * (`ApprovalDecisionResult`) declares the throw intentional.
+ *
+ * ⛔ This module does NOT change that posture. The maintainer ruled on
+ * 2026-09-04 (decision batch #37, option B) that the door **keeps its status
+ * code** — the 500-class `RESUME_FAILED` — because the effect landing while
+ * the run strands is still a failure. What the ruling changed is that the
+ * throw must be *truthful*: the facts a caller needs were being discarded.
+ *
+ * ## What was being discarded, measured
+ *
+ * Three states coexist after such a call: the caller reads 500, the request
+ * IS in its terminal status, and the run is stranded. A caller — human,
+ * script, or agent — reads 500 as "the rejection did not happen" and retries
+ * or escalates. It did happen. Before this module the only carrier of that
+ * fact was English prose in `error`, so an operator had to regex the run id
+ * out of a sentence, and nothing said whether the run was repairable at all.
+ *
+ * Meanwhile the engine already knew. `AutomationResult.status: 'stranded'`
+ * (`@objectstack/spec`, `automation-service.ts`) is stamped on exactly the
+ * exit that journals a repair snapshot — the shape-4 name from #13937 — and
+ * it is distinct from `'failed'` on purpose: `'failed'` says the run ran and
+ * was rejected, `'stranded'` says a recorded continuation stopped mid-flight
+ * and an operator has something to repair. It had a producer and, until this
+ * module, **zero consumers**: the approvals door read only
+ * `success` / `code` / `error` off the resume result and dropped it one line
+ * before the envelope was built.
+ *
+ * ## Why it lives in `@objectstack/types`
+ *
+ * Same Home rule as {@link ValidationFailureDetails} one file over: the
+ * PRODUCER is `@objectstack/plugin-approvals` and the CONSUMER is the REST
+ * door in `@objectstack/rest`, and rest cannot import a plugin. Both already
+ * depend on this package, so the shared declaration adds no dependency edge —
+ * and keeping the constructor and the reader in ONE module is what stops the
+ * two sides from drifting into a stringly-typed agreement about a property
+ * name.
+ *
+ * ⛔ Deliberately NOT a tolerant reader. There is no alias chain and no prose
+ * parsing: a body either carries the four facts the producer attached, or the
+ * response is exactly what it was before. A `RESUME_FAILED` raised by
+ * something that never had a decision to report (a test double, a future
+ * caller) must not be dressed up as one.
+ */
+/**
+ * The four facts a stranded decision publishes alongside its `code` and
+ * `error`. Every field is present or the whole envelope is absent — a partial
+ * one would let a consumer branch on `finalized === undefined` and read it as
+ * "the decision did not stand", which is the exact misreading this exists to
+ * end.
+ */
+interface StrandedDecisionDetails {
+    /**
+     * Always `true`. The decision reached a terminal state and is durable; the
+     * 5xx is about the run, never about the decision. Spelled as a literal
+     * rather than omitted so a consumer reads a fact instead of an absence.
+     */
+    finalized: true;
+    /**
+     * Which outcome was recorded — `'approve'` / `'reject'` for a decision, and
+     * the sibling doors on the same path for the rest (`'revise'` on a
+     * send-back, `'resubmit'`). Free-form by design: the vocabulary belongs to
+     * the producing service, not to this recogniser.
+     */
+    decision: string;
+    /** The stranded run. The one identifier an operator needs to act. */
+    runId: string;
+    /**
+     * Whether the engine says this run can still be repaired — derived from the
+     * engine's own discriminator (`AutomationResult.status === 'stranded'`),
+     * never from the message text and never assumed.
+     *
+     * `false` is the honest answer for every other exit, including the ones
+     * that report no status at all (a lost run, an engine that predates the
+     * discriminator). ⛔ Absence of the signal is not repairability: promising a
+     * repair verb that will refuse is worse than promising nothing.
+     */
+    repairable: boolean;
+}
+/**
+ * Structured details for a thrown stranded-decision failure, or `undefined`
+ * when `err` is not one.
+ *
+ * Callers use the `undefined` result as the predicate and the returned object
+ * as the payload, so the two can never disagree — the same contract
+ * `validationFailureDetails` keeps one module over. Every field is validated:
+ * a malformed carrier answers `undefined` rather than putting a half-envelope
+ * on the wire.
+ */
+declare function strandedDecisionDetails(err: unknown): StrandedDecisionDetails | undefined;
+/**
+ * The CONSTRUCTOR for the shape {@link strandedDecisionDetails} recognises —
+ * kept in the same module so the two can never drift.
+ *
+ * The message stays the producer's own, unchanged: the prose is what a human
+ * reads in a log, the details are what a machine reads on the wire, and this
+ * ruling added the second without touching the first.
+ */
+declare function strandedDecisionFailure(message: string, details: StrandedDecisionDetails): Error;
+
 /**
  * The one home for Postgres' `«sub-object» "x" of relation "y" …` phrasing
  * (#6615).
@@ -1931,4 +2045,4 @@ interface RuntimePlugin {
     onStart?: (ctx: RuntimeContext) => void | Promise<void>;
 }
 
-export { DRIVER_TARGETED_TABLE, type EnvelopeResponse, GLOBAL_UNIQUE_CONFIRMATION_REQUIRED, GLOBAL_UNIQUE_ISOLATED_PRESCRIPTION, type GlobalUniqueAttestation, type GlobalUniqueFinding, type IKernel, INTERNAL_ERROR_MESSAGE, type KeysetPageQuery, type KeysetWalk, type KeysetWalkOptions, PLATFORM_OWNER_EMAIL_ENV, type RuntimeContext, type RuntimePlugin, SERVER_FAULT_LOG_PREFIX, type ServerFaultLogInput, type ServerFaultProvenance, type ServerFaultRequest, type ThrownHttpError, VALIDATION_FAILED_STATUS, type ValidationFailureDetails, _resetEnvDeprecationWarnings, buildGlobalUniqueStopMessage, collectConfiguredLocales, collectGlobalUniques, declareTargetedTable, declaredIndexUniqueIsGlobal, declaredUserMessage, declaresServerFault, demotedDeclaredCode, describeFaultRequest, describeGlobalUniqueFinding, emitDegradedBootBanner, fieldUniqueIsGlobal, fieldsFromZodIssues, globalUniqueFindingId, isEmailVerifiedUserRow, isMcpServerEnabled, isMissingTableError, isModuleNotFoundError, isPlatformOwnedObject, isRelationSubObjectPhrase, isSchemaAlreadyExistsError, isServerFault, isUnbackedConflictTargetError, isUniqueViolationError, keysetWalk, logServerFault, looksLikeInternalErrorLeak, matchMissingColumnOfRelation, postureGatesGlobalUniques, readEnvWithDeprecation, recordGlobalUniqueAttestation, resolveAllowDegradedTenancy, resolveAllowDevPlugin, resolveAllowDriverConnectFailure, resolveMcpStdioAutoStart, resolveMultiOrgEnabled, resolveOrgLimit, resolveOrgMembershipLimit, resolvePlatformOwnerEmail, resolveSandboxTimeoutMs, resolveSearchPinyinEnabled, resolveTenancyPosture, resolveThrownHttpError, sendError, sendOk, serverFaultLogMessage, serverFaultLogMeta, serverFaultProvenance, stampSearchPinyinEnabled, targetedTableOf, unconfirmedGlobalUniques, uniqueViolationColumn, validationFailure, validationFailureDetails };
+export { DRIVER_TARGETED_TABLE, type EnvelopeResponse, GLOBAL_UNIQUE_CONFIRMATION_REQUIRED, GLOBAL_UNIQUE_ISOLATED_PRESCRIPTION, type GlobalUniqueAttestation, type GlobalUniqueFinding, type IKernel, INTERNAL_ERROR_MESSAGE, type KeysetPageQuery, type KeysetWalk, type KeysetWalkOptions, PLATFORM_OWNER_EMAIL_ENV, type RuntimeContext, type RuntimePlugin, SERVER_FAULT_LOG_PREFIX, type ServerFaultLogInput, type ServerFaultProvenance, type ServerFaultRequest, type StrandedDecisionDetails, type ThrownHttpError, VALIDATION_FAILED_STATUS, type ValidationFailureDetails, _resetEnvDeprecationWarnings, buildGlobalUniqueStopMessage, collectConfiguredLocales, collectGlobalUniques, declareTargetedTable, declaredIndexUniqueIsGlobal, declaredUserMessage, declaresServerFault, demotedDeclaredCode, describeFaultRequest, describeGlobalUniqueFinding, emitDegradedBootBanner, fieldUniqueIsGlobal, fieldsFromZodIssues, globalUniqueFindingId, isEmailVerifiedUserRow, isMcpServerEnabled, isMissingTableError, isModuleNotFoundError, isPlatformOwnedObject, isRelationSubObjectPhrase, isSchemaAlreadyExistsError, isServerFault, isUnbackedConflictTargetError, isUniqueViolationError, keysetWalk, logServerFault, looksLikeInternalErrorLeak, matchMissingColumnOfRelation, postureGatesGlobalUniques, readEnvWithDeprecation, recordGlobalUniqueAttestation, resolveAllowDegradedTenancy, resolveAllowDevPlugin, resolveAllowDriverConnectFailure, resolveMcpStdioAutoStart, resolveMultiOrgEnabled, resolveOrgLimit, resolveOrgMembershipLimit, resolvePlatformOwnerEmail, resolveSandboxTimeoutMs, resolveSearchPinyinEnabled, resolveTenancyPosture, resolveThrownHttpError, sendError, sendOk, serverFaultLogMessage, serverFaultLogMeta, serverFaultProvenance, stampSearchPinyinEnabled, strandedDecisionDetails, strandedDecisionFailure, targetedTableOf, unconfirmedGlobalUniques, uniqueViolationColumn, validationFailure, validationFailureDetails };

package/dist/index.d.ts

@@ -475,8 +475,10 @@ declare function _resetEnvDeprecationWarnings(): void;
  * "Do not ship driver internals to clients" is a property of the HTTP
  * boundary, not of one router, so the predicate lives here — the package both
  * `@objectstack/rest` and `@objectstack/runtime` already depend on — and each
- * boundary applies it in its own envelope. One heuristic, one place to widen
- * when a new dialect's phrasing shows up.
+ * boundary applies it in its own envelope. One heuristic, one place — and
+ * since #16019 a FROZEN one: a phrasing it does not recognise is closed by the
+ * producer declaring its fault, never by a new row here (the ruling is
+ * recorded on {@link DIALECT_LEAK_PHRASINGS}).
  *
  * Deliberately a *heuristic over the message*, not a driver taxonomy: these
  * errors arrive as plain `Error`s from a half-dozen dialects with no shared
@@ -1340,6 +1342,118 @@ declare function fieldsFromZodIssues(issues: Array<{
     message: string;
 }>;
 
+/**
+ * The machine-readable half of a `RESUME_FAILED` — a decision that is durably
+ * recorded whose flow run could not be resumed (#13807).
+ *
+ * ## The condition
+ *
+ * An approval decision finalises: the `sys_approval_request` row flips to its
+ * terminal status, the audit action is written, the record's mirrored status
+ * field advances — and only THEN is the owning flow run resumed. When that
+ * resume fails the writes are already durable, so the outcome stands and the
+ * run is stranded. `@objectstack/plugin-approvals` throws rather than
+ * answering `resumed: false`, deliberately: a recorded decision whose flow
+ * never advances is #4420's zombie half-state, and the contract
+ * (`ApprovalDecisionResult`) declares the throw intentional.
+ *
+ * ⛔ This module does NOT change that posture. The maintainer ruled on
+ * 2026-09-04 (decision batch #37, option B) that the door **keeps its status
+ * code** — the 500-class `RESUME_FAILED` — because the effect landing while
+ * the run strands is still a failure. What the ruling changed is that the
+ * throw must be *truthful*: the facts a caller needs were being discarded.
+ *
+ * ## What was being discarded, measured
+ *
+ * Three states coexist after such a call: the caller reads 500, the request
+ * IS in its terminal status, and the run is stranded. A caller — human,
+ * script, or agent — reads 500 as "the rejection did not happen" and retries
+ * or escalates. It did happen. Before this module the only carrier of that
+ * fact was English prose in `error`, so an operator had to regex the run id
+ * out of a sentence, and nothing said whether the run was repairable at all.
+ *
+ * Meanwhile the engine already knew. `AutomationResult.status: 'stranded'`
+ * (`@objectstack/spec`, `automation-service.ts`) is stamped on exactly the
+ * exit that journals a repair snapshot — the shape-4 name from #13937 — and
+ * it is distinct from `'failed'` on purpose: `'failed'` says the run ran and
+ * was rejected, `'stranded'` says a recorded continuation stopped mid-flight
+ * and an operator has something to repair. It had a producer and, until this
+ * module, **zero consumers**: the approvals door read only
+ * `success` / `code` / `error` off the resume result and dropped it one line
+ * before the envelope was built.
+ *
+ * ## Why it lives in `@objectstack/types`
+ *
+ * Same Home rule as {@link ValidationFailureDetails} one file over: the
+ * PRODUCER is `@objectstack/plugin-approvals` and the CONSUMER is the REST
+ * door in `@objectstack/rest`, and rest cannot import a plugin. Both already
+ * depend on this package, so the shared declaration adds no dependency edge —
+ * and keeping the constructor and the reader in ONE module is what stops the
+ * two sides from drifting into a stringly-typed agreement about a property
+ * name.
+ *
+ * ⛔ Deliberately NOT a tolerant reader. There is no alias chain and no prose
+ * parsing: a body either carries the four facts the producer attached, or the
+ * response is exactly what it was before. A `RESUME_FAILED` raised by
+ * something that never had a decision to report (a test double, a future
+ * caller) must not be dressed up as one.
+ */
+/**
+ * The four facts a stranded decision publishes alongside its `code` and
+ * `error`. Every field is present or the whole envelope is absent — a partial
+ * one would let a consumer branch on `finalized === undefined` and read it as
+ * "the decision did not stand", which is the exact misreading this exists to
+ * end.
+ */
+interface StrandedDecisionDetails {
+    /**
+     * Always `true`. The decision reached a terminal state and is durable; the
+     * 5xx is about the run, never about the decision. Spelled as a literal
+     * rather than omitted so a consumer reads a fact instead of an absence.
+     */
+    finalized: true;
+    /**
+     * Which outcome was recorded — `'approve'` / `'reject'` for a decision, and
+     * the sibling doors on the same path for the rest (`'revise'` on a
+     * send-back, `'resubmit'`). Free-form by design: the vocabulary belongs to
+     * the producing service, not to this recogniser.
+     */
+    decision: string;
+    /** The stranded run. The one identifier an operator needs to act. */
+    runId: string;
+    /**
+     * Whether the engine says this run can still be repaired — derived from the
+     * engine's own discriminator (`AutomationResult.status === 'stranded'`),
+     * never from the message text and never assumed.
+     *
+     * `false` is the honest answer for every other exit, including the ones
+     * that report no status at all (a lost run, an engine that predates the
+     * discriminator). ⛔ Absence of the signal is not repairability: promising a
+     * repair verb that will refuse is worse than promising nothing.
+     */
+    repairable: boolean;
+}
+/**
+ * Structured details for a thrown stranded-decision failure, or `undefined`
+ * when `err` is not one.
+ *
+ * Callers use the `undefined` result as the predicate and the returned object
+ * as the payload, so the two can never disagree — the same contract
+ * `validationFailureDetails` keeps one module over. Every field is validated:
+ * a malformed carrier answers `undefined` rather than putting a half-envelope
+ * on the wire.
+ */
+declare function strandedDecisionDetails(err: unknown): StrandedDecisionDetails | undefined;
+/**
+ * The CONSTRUCTOR for the shape {@link strandedDecisionDetails} recognises —
+ * kept in the same module so the two can never drift.
+ *
+ * The message stays the producer's own, unchanged: the prose is what a human
+ * reads in a log, the details are what a machine reads on the wire, and this
+ * ruling added the second without touching the first.
+ */
+declare function strandedDecisionFailure(message: string, details: StrandedDecisionDetails): Error;
+
 /**
  * The one home for Postgres' `«sub-object» "x" of relation "y" …` phrasing
  * (#6615).
@@ -1931,4 +2045,4 @@ interface RuntimePlugin {
     onStart?: (ctx: RuntimeContext) => void | Promise<void>;
 }
 
-export { DRIVER_TARGETED_TABLE, type EnvelopeResponse, GLOBAL_UNIQUE_CONFIRMATION_REQUIRED, GLOBAL_UNIQUE_ISOLATED_PRESCRIPTION, type GlobalUniqueAttestation, type GlobalUniqueFinding, type IKernel, INTERNAL_ERROR_MESSAGE, type KeysetPageQuery, type KeysetWalk, type KeysetWalkOptions, PLATFORM_OWNER_EMAIL_ENV, type RuntimeContext, type RuntimePlugin, SERVER_FAULT_LOG_PREFIX, type ServerFaultLogInput, type ServerFaultProvenance, type ServerFaultRequest, type ThrownHttpError, VALIDATION_FAILED_STATUS, type ValidationFailureDetails, _resetEnvDeprecationWarnings, buildGlobalUniqueStopMessage, collectConfiguredLocales, collectGlobalUniques, declareTargetedTable, declaredIndexUniqueIsGlobal, declaredUserMessage, declaresServerFault, demotedDeclaredCode, describeFaultRequest, describeGlobalUniqueFinding, emitDegradedBootBanner, fieldUniqueIsGlobal, fieldsFromZodIssues, globalUniqueFindingId, isEmailVerifiedUserRow, isMcpServerEnabled, isMissingTableError, isModuleNotFoundError, isPlatformOwnedObject, isRelationSubObjectPhrase, isSchemaAlreadyExistsError, isServerFault, isUnbackedConflictTargetError, isUniqueViolationError, keysetWalk, logServerFault, looksLikeInternalErrorLeak, matchMissingColumnOfRelation, postureGatesGlobalUniques, readEnvWithDeprecation, recordGlobalUniqueAttestation, resolveAllowDegradedTenancy, resolveAllowDevPlugin, resolveAllowDriverConnectFailure, resolveMcpStdioAutoStart, resolveMultiOrgEnabled, resolveOrgLimit, resolveOrgMembershipLimit, resolvePlatformOwnerEmail, resolveSandboxTimeoutMs, resolveSearchPinyinEnabled, resolveTenancyPosture, resolveThrownHttpError, sendError, sendOk, serverFaultLogMessage, serverFaultLogMeta, serverFaultProvenance, stampSearchPinyinEnabled, targetedTableOf, unconfirmedGlobalUniques, uniqueViolationColumn, validationFailure, validationFailureDetails };
+export { DRIVER_TARGETED_TABLE, type EnvelopeResponse, GLOBAL_UNIQUE_CONFIRMATION_REQUIRED, GLOBAL_UNIQUE_ISOLATED_PRESCRIPTION, type GlobalUniqueAttestation, type GlobalUniqueFinding, type IKernel, INTERNAL_ERROR_MESSAGE, type KeysetPageQuery, type KeysetWalk, type KeysetWalkOptions, PLATFORM_OWNER_EMAIL_ENV, type RuntimeContext, type RuntimePlugin, SERVER_FAULT_LOG_PREFIX, type ServerFaultLogInput, type ServerFaultProvenance, type ServerFaultRequest, type StrandedDecisionDetails, type ThrownHttpError, VALIDATION_FAILED_STATUS, type ValidationFailureDetails, _resetEnvDeprecationWarnings, buildGlobalUniqueStopMessage, collectConfiguredLocales, collectGlobalUniques, declareTargetedTable, declaredIndexUniqueIsGlobal, declaredUserMessage, declaresServerFault, demotedDeclaredCode, describeFaultRequest, describeGlobalUniqueFinding, emitDegradedBootBanner, fieldUniqueIsGlobal, fieldsFromZodIssues, globalUniqueFindingId, isEmailVerifiedUserRow, isMcpServerEnabled, isMissingTableError, isModuleNotFoundError, isPlatformOwnedObject, isRelationSubObjectPhrase, isSchemaAlreadyExistsError, isServerFault, isUnbackedConflictTargetError, isUniqueViolationError, keysetWalk, logServerFault, looksLikeInternalErrorLeak, matchMissingColumnOfRelation, postureGatesGlobalUniques, readEnvWithDeprecation, recordGlobalUniqueAttestation, resolveAllowDegradedTenancy, resolveAllowDevPlugin, resolveAllowDriverConnectFailure, resolveMcpStdioAutoStart, resolveMultiOrgEnabled, resolveOrgLimit, resolveOrgMembershipLimit, resolvePlatformOwnerEmail, resolveSandboxTimeoutMs, resolveSearchPinyinEnabled, resolveTenancyPosture, resolveThrownHttpError, sendError, sendOk, serverFaultLogMessage, serverFaultLogMeta, serverFaultProvenance, stampSearchPinyinEnabled, strandedDecisionDetails, strandedDecisionFailure, targetedTableOf, unconfirmedGlobalUniques, uniqueViolationColumn, validationFailure, validationFailureDetails };

package/dist/index.js

@@ -77,6 +77,8 @@ __export(index_exports, {
   serverFaultLogMeta: () => serverFaultLogMeta,
   serverFaultProvenance: () => serverFaultProvenance,
   stampSearchPinyinEnabled: () => stampSearchPinyinEnabled,
+  strandedDecisionDetails: () => strandedDecisionDetails,
+  strandedDecisionFailure: () => strandedDecisionFailure,
   targetedTableOf: () => targetedTableOf,
   unconfirmedGlobalUniques: () => unconfirmedGlobalUniques,
   uniqueViolationColumn: () => uniqueViolationColumn,
@@ -501,6 +503,24 @@ function demotedDeclaredCode(thrown) {
   return thrown.declaredCode !== void 0 && thrown.declaredCode !== thrown.code ? thrown.declaredCode : void 0;
 }
 
+// src/stranded-decision.ts
+var CARRIER = "strandedDecision";
+function strandedDecisionDetails(err) {
+  const carried = err?.[CARRIER];
+  if (!carried || typeof carried !== "object") return void 0;
+  const d = carried;
+  if (d.finalized !== true) return void 0;
+  if (typeof d.decision !== "string" || d.decision === "") return void 0;
+  if (typeof d.runId !== "string" || d.runId === "") return void 0;
+  if (typeof d.repairable !== "boolean") return void 0;
+  return { finalized: true, decision: d.decision, runId: d.runId, repairable: d.repairable };
+}
+function strandedDecisionFailure(message, details) {
+  const err = new Error(message);
+  err[CARRIER] = details;
+  return err;
+}
+
 // src/relation-sub-object.ts
 function matchMissingColumnOfRelation(message) {
   return MISSING_COLUMN_OF_RELATION.exec(message)?.[1];
@@ -933,6 +953,8 @@ function postureGatesGlobalUniques(posture) {
   serverFaultLogMeta,
   serverFaultProvenance,
   stampSearchPinyinEnabled,
+  strandedDecisionDetails,
+  strandedDecisionFailure,
   targetedTableOf,
   unconfirmedGlobalUniques,
   uniqueViolationColumn,