run-dmcp 0.1.0 → 0.2.0

package/dist/timeline/constrained.d.ts

@@ -0,0 +1,220 @@
+import { type T } from "./t.js";
+/**
+ * The choke point (design §5.4 option (C), Phase 3 step 2): the ONE place a
+ * constrained numeric fact key is written, and the ONE place `resources`'
+ * former `resource_history` table is replaced by reading the interval-
+ * versioned `facts` the projection triggers (projection.ts) already produce.
+ *
+ * Before this module existed, "what did this value used to be" had two
+ * disconnected answers -- a bespoke `resource_history` table that only
+ * `updateResourceValue`/`transferResourceValue` (src/tools/resource.ts) wrote
+ * to, and the timeline's own `facts`, which the projection triggers were
+ * ALREADY appending to on every write, unread by anyone. Two write paths for
+ * the same fact is exactly the failure root CLAUDE.md's "engine records
+ * decisions" framing and the project's own history (the predecessor's
+ * `resource_history`/`relationship_history`, engineVocabulary.test.ts's
+ * epigraph) warn about generalizing badly: something gets added because one
+ * caller needed it, nothing generalizes the idea, and the concept of
+ * versioning ends up living in exactly as many places as someone happened to
+ * ask for it. This module collapses that back to one: `writeConstrainedValue`
+ * is the only way a constrained numeric value changes, and `valueHistory` is
+ * built entirely from what the timeline already recorded.
+ *
+ * IMPORT DIRECTION IS LOAD-BEARING. This file imports nothing from
+ * `src/tools/` -- registry.ts's doc comment explains why in detail, and the
+ * short version is: `src/tools/constraint.ts` already imports
+ * `src/tools/resource.ts` (for `getResource`), and `src/tools/resource.ts`
+ * needs to import THIS module (to delegate `updateResourceValue`/
+ * `transferResourceValue` to it). If this module reached back into
+ * `src/tools/` for anything -- `getResource`, a resource-shaped type, a
+ * resource-specific constant -- that would close
+ * `tools/resource.ts -> timeline/constrained.ts -> tools/*` into a cycle.
+ * Every value this module needs about "the entity currently reads a column
+ * with this key" comes from the timeline's own vocabulary instead:
+ * `entities`, `PROJECTED_TABLES`, `liveColumns` (projection.ts) and
+ * `constraintsFor`/`conservedConstraintFor` (registry.ts).
+ */
+/**
+ * One recorded transition of a constrained numeric fact key. A row, never a
+ * verdict (hard rule 2) -- there is no `wasClamped`, no `violatedConstraint`,
+ * just what changed, when, and (if a constrained write made it) why.
+ */
+export interface ValueTransition {
+    entityId: string;
+    key: string;
+    previousValue: number;
+    newValue: number;
+    delta: number;
+    reason: string | null;
+    /** Where on the timeline this landed. */
+    t: T;
+    /** The fact this write opened; null when the write changed nothing (no
+     *  new interval opens for a value that didn't move -- see
+     *  `applyLiveWrite`). */
+    factId: string | null;
+    /** The annotation event this write logged; null for a transition no
+     *  constrained write made (an unannotated fact-only transition -- a
+     *  direct column write, a bounds re-clamp, a startup reconciliation). */
+    eventId: string | null;
+    /** Wall-clock ISO stamp recorded by the choke point; null when
+     *  unannotated. */
+    at: string | null;
+}
+/**
+ * A2: the single site where the declared constraint family (design §5.3) --
+ * `monotonic`, `bounded`, `conserved`, and (issue #13) `resolve_only` -- is
+ * evaluated against an intended change. Every one of `checkResourceConstraints()`
+ * and `checkBoundedAndMonotonicConstraints()`'s (formerly src/tools/constraint.ts)
+ * rules lives here now and ONLY here -- grep the tree for
+ * `constraint.direction ===` or `constraint.kind === "bounded"` and this file
+ * is the only hit outside a test.
+ *
+ * Reads via `constraintsFor(entityId, key)` (registry.ts), not
+ * `allConstraintsForEntity` -- this is the behavioral point of Phase 3 step
+ * 1's key-scoping: a `monotonic` (or, now, `resolve_only`) constraint
+ * declared on one fact key must never reach a write to a different key on
+ * the same entity, even though every constraint declared through today's
+ * `declare*()` functions other than `declareResolveOnlyConstraint` happens
+ * to govern `'value'`.
+ *
+ * `bounds` is optional. When a caller has no bounds to check against (e.g.
+ * `updateResource`'s own guard below, which is not itself moving a value
+ * against declared min/max -- it is refusing a conserved reclamp), the
+ * `bounded` branch is simply skipped rather than crashing on a missing
+ * object. `monotonic` and `conserved` need no bounds and are always
+ * evaluated when applicable.
+ *
+ * MESSAGE PRESERVATION: every string thrown below is copied verbatim from
+ * `checkResourceConstraints`/`checkBoundedAndMonotonicConstraints` as they
+ * stood before this module existed -- `conserved.test.ts` asserts against
+ * the conserved-rejection text by regex, and nothing here is worth rewording
+ * away from wording a real caller may already be matching on.
+ */
+export declare function assertConstraintsAllow(params: {
+    entityId: string;
+    key: string;
+    previousValue: number;
+    intendedValue: number;
+    bounds?: {
+        minValue: number | null;
+        maxValue: number | null;
+    };
+    /** "reject" -- a direct single-entity write to a conserved member is
+     *  refused (the ambiguity has no answer). "allow" -- the caller is the
+     *  counterpart-carrying transfer, the one write that CAN preserve the
+     *  total. */
+    conservedMemberWrite: "reject" | "allow";
+    /** Appended to a conserved rejection in place of the default sentence
+     *  about `update_resource_value`, so the message names the operation the
+     *  caller actually performed. */
+    context?: string;
+}): void;
+/**
+ * A3: the only way a constrained numeric value changes. Resolve, check,
+ * clamp, write -- in that order, and the order is load-bearing: clamping
+ * BEFORE the constraint check would let a declared `bounded` constraint's
+ * rejection be silently satisfied by the very clamp it exists to prevent
+ * (an intended value of 150 against a [0, 100] bound would arrive at the
+ * check already clamped to 100, and a `bounded` constraint's whole point is
+ * to refuse 150, not to see 100). Clamping AFTER means the constraint check
+ * always sees the caller's actual, unclamped intent.
+ */
+export declare function writeConstrainedValue(params: {
+    entityId: string;
+    key: string;
+    mode: "delta" | "set";
+    value: number;
+    reason?: string | null;
+    bounds?: {
+        minValue: number | null;
+        maxValue: number | null;
+    };
+    context?: string;
+}): ValueTransition;
+/**
+ * A4: the counterpart-carrying two-leg write for conserved sets. Ported from
+ * `transferResourceValue` (src/tools/resource.ts) minus its argument
+ * validation (self-transfer, non-finite, negative, not-found), which stays
+ * in resource.ts because it is about resource IDENTITY, not about the
+ * constraint family this module owns -- see the doc comment there.
+ *
+ * Checks run BEFORE the transaction (membership, then bounded/monotonic on
+ * both legs, then the never-clamp bounds rejection), exactly as
+ * `transferResourceValue` ordered them -- a transfer that is going to be
+ * rejected should never touch either live row. Both legs' writes, plus the
+ * defense-in-depth sum re-verification, land in ONE `withTransaction()`.
+ */
+export declare function transferConstrainedValue(params: {
+    fromEntityId: string;
+    toEntityId: string;
+    key: string;
+    amount: number;
+    reason?: string | null;
+    fromBounds?: {
+        minValue: number | null;
+        maxValue: number | null;
+    };
+    toBounds?: {
+        minValue: number | null;
+        maxValue: number | null;
+    };
+    fromLabel?: string;
+    toLabel?: string;
+}): {
+    from: ValueTransition;
+    to: ValueTransition;
+};
+/**
+ * A5: the payoff -- `valueHistory` is built ENTIRELY from the timeline
+ * (`facts` and `events`), with no `resource_history` in sight, because by
+ * this point in the merge there is no `resource_history` writer left to
+ * read from.
+ *
+ * Two sources, both scoped to `(entityId, key)`:
+ *
+ *   1. every FACT TRANSITION: consecutive facts, ordered `(valid_from_t,
+ *      rowid)`, paired so each fact after the first supplies a
+ *      previousValue/newValue/delta. The first fact is the value's
+ *      CREATION, not a change -- `createResource` writes no history row
+ *      today, and this function must not invent one, so the pairing loop
+ *      starts at index 1, never 0.
+ *   2. every `"value.changed"` annotation event whose `causes.$.fact_id` is
+ *      JSON null -- a constrained write that changed nothing. A no-op write
+ *      opens no fact (see `applyLiveWrite`), so its annotation event is the
+ *      ONLY record of it; without this second source, a zero-amount
+ *      transfer or a zero-delta update would silently vanish from history,
+ *      which is exactly what conserved.test.ts's "logged even though
+ *      nothing moved" assertions were written against.
+ *
+ * Fact transitions are joined to their annotation (if any) by
+ * `json_extract(causes, '$.fact_id') = facts.id` -- an EXACT, unique link,
+ * because `applyLiveWrite` recorded the fact id at write time. This is
+ * deliberately stronger than irreversible.ts's `findOpenedByEventId`, which
+ * has to approximate the same relationship via `(at_t, row_id)` because the
+ * projection triggers that write `row_id` have no fact id to record at the
+ * point they fire (issue #2 predates this module). Here, recording the real
+ * id costs nothing extra and removes the approximation entirely.
+ *
+ * `json_valid(causes)` guards every extraction, matching irreversible.ts's
+ * `CASE WHEN json_valid(causes) THEN causes END` idiom for the same reason
+ * given there: `events.causes` has no CHECK constraint, timeline import
+ * (export.ts) carries it through verbatim by design, and SQLite's
+ * `json_extract` raises for the WHOLE query -- not just the offending row --
+ * when it meets a value that isn't JSON. A provenance hop must never be able
+ * to fail the query it annotates.
+ *
+ * Rows with no matching annotation (a direct column write, a bounds
+ * re-clamp, a startup reconciliation) come back with `reason: null`,
+ * `eventId: null`, `at: null` -- MORE history than `resource_history` ever
+ * held, because that table only ever got a row when
+ * `updateResourceValue`/`transferResourceValue` themselves wrote one.
+ *
+ * Ordered newest-first by `(t, rowid)` descending, matching
+ * `resource_history`'s old `ORDER BY timestamp DESC` in spirit -- but by the
+ * timeline's own axis, `t`, not by wall-clock time, because an unannotated
+ * transition has no wall-clock stamp to sort by and `t` is the one ordering
+ * this whole codebase agrees on (t.ts). `rowid` is the tiebreak for the rare
+ * case two rows share a `t`, mirroring `changes.ts`'s own tiebreak
+ * discipline. `limit` applies after ordering, never before.
+ */
+export declare function valueHistory(entityId: string, key: string, limit?: number): ValueTransition[];