@substrat-run/contracts 0.133.0 → 0.135.0

package/dist/refusal.js

@@ -0,0 +1,93 @@
+import { z } from 'zod';
+import { actor } from './events.js';
+import { impersonationStamp } from './impersonation.js';
+import { scopeId, tenantId } from './ids.js';
+import { lifecycleActorKind } from './lifecycle-flow.js';
+/**
+ * The read side of the refusal log (#1745) — a scope-local record of every lifecycle move
+ * `assertTransition` refused and the operation failed with, written on the failure path as
+ * a write of its own AFTER the rollback it is evidence of.
+ *
+ * The denial log's sibling, and read the same way (`permissionDenial` / `denialFilter`):
+ * a denial is the permission model disagreeing with an actor, a refusal is the lifecycle
+ * disagreeing with one. `lifecycleFlow` already counts these per (from, attempted) for the
+ * process map; this is the row read beneath that count — WHICH record, WHO, in WHICH call —
+ * so a red stub reaches the requests that drew it.
+ *
+ * The same two properties hold as for denials: the volume is actor-influenceable (a client
+ * retrying an illegal move mints a row per attempt), and the window is a storage bound,
+ * not a retention promise — rows drain rather than expire.
+ */
+/** How many refusal rows an unbounded read returns — a screenful, newest-first. */
+export const DEFAULT_REFUSAL_LIMIT = 50;
+/** The hard ceiling on one page of refusal rows. */
+export const REFUSAL_LIMIT_MAX = 200;
+/**
+ * One recorded refusal.
+ *
+ * `kind` is `'transition'` for every row today; a K-38 guard refusal is the next kind,
+ * recorded in the same table. It is read as text rather than a closed enum so a reader
+ * built now does not reject the row a later kernel writes.
+ */
+export const refusalRecord = z.object({
+    /** ULID — chronological, so it is also the sort key. */
+    id: z.string().min(1),
+    kind: z.string().min(1),
+    /**
+     * The problem code the operation failed with — `invalid_transition` for a transition
+     * refusal, which is the `reason` on the 409 the caller received. Null for a kind this
+     * reader does not know the code of.
+     */
+    reason: z.string().nullable(),
+    /** WHO attempted the move: a principal, a `{ system }` module, a `{ connection }`, … */
+    actor,
+    /** The actor's kind, read off its stored shape — what the process map counts by. */
+    actorKind: lifecycleActorKind,
+    tenantId,
+    scopeId: scopeId.nullable(),
+    /** The record the move was refused on. Null when the caller of `assertTransition` did not name it. */
+    entityType: z.string().nullable(),
+    entityId: z.string().nullable(),
+    /** The state the record was in. */
+    fromState: z.string(),
+    /** Where the operation leads where it IS legal; null when that is not one state. */
+    attemptedState: z.string().nullable(),
+    /** The lifecycle's operation — what the edge is keyed by. */
+    operation: z.string(),
+    /** The `invoke()` string the call ran as. The same as `operation` for every caller today. */
+    invokedOperation: z.string().nullable(),
+    /** The staff actor and session behind the attempt (K-42), or null for the ordinary case. */
+    impersonation: impersonationStamp.nullable(),
+    /** The invocation the refusal happened during — the join to the rest of its request. */
+    invocationId: z.string().nullable(),
+    /** ISO 8601. */
+    at: z.string().min(1),
+    drainedAt: z.string().nullable(),
+    /**
+     * Why this row could not be read whole — ABSENT on every row the kernel wrote. Same rule
+     * as `permissionDenial.decodeError` (#1636): an undecodable actor or impersonation reads
+     * as its empty value beside this, rather than taking the page down.
+     */
+    decodeError: z.string().min(1).optional(),
+});
+/**
+ * What narrows a refusal read. Every field is an exact match except the `since`/`until`
+ * bounds on `at` (inclusive lower, exclusive upper) — the denial filter's convention, so
+ * adjacent windows tile.
+ *
+ * `actor` takes the LOGICAL actor, as `denialFilter.actor` does: a bare principal ULID or
+ * the object form for any other kind. The stored encoding is the reader's problem.
+ */
+export const refusalFilter = z.object({
+    entityType: z.string().min(1).optional(),
+    entityId: z.string().min(1).optional(),
+    actor: z.string().min(1).optional(),
+    operation: z.string().min(1).optional(),
+    invocationId: z.string().min(1).optional(),
+    /** ISO 8601, inclusive. */
+    since: z.string().min(1).optional(),
+    /** ISO 8601, exclusive. */
+    until: z.string().min(1).optional(),
+    limit: z.number().int().min(1).max(REFUSAL_LIMIT_MAX).optional(),
+});
+//# sourceMappingURL=refusal.js.map

package/dist/refusal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"refusal.js","sourceRoot":"","sources":["../src/refusal.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@substrat-run/contracts",
-  "version": "0.133.0",
+  "version": "0.135.0",
   "description": "Substrat kernel contract schemas — Zod is the source of truth (master plan D-22); OAS/JSON Schema are emitted artifacts",
   "license": "Apache-2.0",
   "repository": {