NUMERIC-QUANTITIES-V1: implementation complete (accrue deltas + numeric predicates)

Implements the GREEN spec end-to-end, both sides wired.

- Data structure: value_type 'delta' (signed increment) beside 'literal'
  (absolute). VALUE_TYPES + extraction schema + dump validation inherit it.
- Phase 1 accrue fold: fold_policy=accrue (RFC-001's reserved axis lit up).
  _fold_accrue = latest numeric literal baseline + sum of strictly-later
  deltas -> FoldResult.quantity (derived total) + _ledger_rows (audit).
  Deterministic, append-only, as-of-correct, concurrency-safe. int+float;
  exact decimal deferred (documented). delta->STATE classifier guardrail.
- Derived totals stay OUT of stored facts: Materialization.quantities
  channel; projector routes accrue results there; porcelain snapshot/state/
  ask/frame_diff surface the total (never a raw delta).
- Phase 2: porcelain where(attribute, op, value) numeric predicate
  (fold-then-compare in Python; non-numeric never matches).
- Docs (founder directive): ADOPTION, HOST-DISCIPLINE, LEXICON, WHITEPAPER
  updated with delta/accrue/quantity/ledger nuances for adopters.

Post-impl Codex review (RED -> all fixed): (1) fold_key reordering restored
so a stray delta/EVENT row can't suppress an unresolved thunk (+ regression
test); (2) state() surfaces the total as fact.value (consistent with
ask/snapshot); (3) resolver constraint-inheritance + promote_accruals skip
accrue/delta (never inherit/promote a delta).

Codex spec-GREEN (3 rounds) + post-impl review. Defaults-preserve: full
suite green. 168 tests (+11).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: 5000Stadia

docs/ADOPTION.md

@@ -67,11 +67,25 @@ Domain outcomes are values you must branch on:
   never guesses below its confidence floor.
 - `FoldResult.conflicted` — the key is under an open truth-maintenance flag;
   `winner` is the engine's holding answer, `conflicting` lists both sides.
+- `FoldResult.quantity` — for attributes declared `fold_policy="accrue"`,
+  the folded numeric total. The `winner` is provenance for the latest ledger
+  row, not the value a host should read.
 - `resolve()` returns the module-level sentinel `UNKNOWN` in
   `observe_or_unknown` worlds when nothing was observed. "I don't know" is a
   representable answer; treat it as one.
 - `Materialization.unresolved` names the frontier in scope; `defaults` are
   render-coherence fills marked `default` — never facts.
+- `Materialization.quantities` carries derived totals as `(entity,
+  attribute, value)` tuples. These totals are not stored assertions.
+
+### Numeric quantities
+
+For fungible counts such as gold, ammo, liters, or charges, declare the
+attribute with `fold_policy="accrue"` before its first data row. A `literal`
+numeric row is an absolute baseline; a `value_type="delta"` row is a signed
+increment. The fold computes `baseline + later deltas`, with the ledger
+available as `FoldResult._ledger_rows` for audit. `int` and `float` are
+supported; exact decimal/fixed-point money is deferred.
 
 ## MUST / NEVER
 
@@ -106,8 +120,10 @@ p.ingest_structured(items, frame=None) -> Receipt
 p.resolve(entity, aspect, frame="canon") -> {status: resolved|unknown|denied, facts}
 p.retract(assertion_id, reason) -> Receipt
 p.snapshot(scope_ids, frame=, as_of=, lens=, budget=, since=) -> dict
-   # contractually ZERO model calls and ZERO writes; id-only scopes
-p.state(entity, attribute, frame=, as_of=) -> {status: known|unknown|conflicted, fact}
+   # contractually ZERO model calls and ZERO writes; id-only scopes; includes quantities
+p.state(entity, attribute, frame=, as_of=) -> {status: known|unknown|conflicted, fact, quantity?}
+p.where(attribute, op, value, frame="canon", as_of=None) -> [entity_id]
+   # op in >=, >, <=, <, ==; compares folded numeric values
 p.locate / p.contents / p.path
 p.events(kind=, participants=str|list, since=, until=, frame=) -> [Event]
 p.frame_diff(a, b, scope, as_of=) -> [Fact]   # semantic diff; divergent values marked

docs/HOST-DISCIPLINE.md

@@ -58,17 +58,22 @@ findable and correlatable.
    for what a thing is) and stable domain vocabulary otherwise. Know whether
    a key is **functional** (one value at a time — `color`, `in`: later
    supersedes earlier) or **set-valued** (`alias`, `connects_to`: values
-   accumulate, never conflict). **Why:** the fold is key-local. Two names
+   accumulate, never conflict), and whether a numeric quantity is
+   **accrue** (absolute baseline plus signed deltas). **Why:** the fold is key-local. Two names
    for the same attribute (`wall_color` vs `color`) split a fact across keys
    the corroborate/conflict machinery will never see meet. (The gate
    canonicalizes a built-in set for you — lean on it, but don't fragment
    what it doesn't know.)
 
 3. **Value & value_type.** `entity` when the value is another id (so walks
    and correlations traverse it); `literal` for scalars/structured;
+   `delta` for a signed numeric increment on an `accrue` attribute;
    `unresolved` for a deliberately-deferred aspect (a *thunk* — see §below).
    Express approximate quantities as **structured bounds** (`{"gte":
    40000}`) so a later precise reading *refines* rather than *contradicts*.
+   For fungible quantities, use `fold_policy="accrue"` and numeric
+   `literal`/`delta` rows; the engine sums int/float values and keeps the
+   ledger append-only.
 
 4. **Time — both axes, deliberately.** `valid_from`/`valid_to` is **world
    time** (when it was true in the world); the engine separately records
@@ -187,6 +192,7 @@ perspective, and reading what comes back honestly.
    |---|---|---|
    | one fact (a key's value) | `state(entity, attribute, …)` | the folded winner + conflict flag |
    | everything about a subject | `snapshot(ids, lens=…)` / `materialize` | a coherent bundle of folded facts |
+   | entities satisfying a numeric bound | `where(attribute, op, value, …)` | ids whose folded numeric value matches |
    | where something is | `locate(entity)` | containment chain, nearest container first |
    | what's inside / co-located | `contents(container)` | members (emptiness = `[]`, derived) |
    | is X reachable from Y | `path(a, b)` | a route, or `None` (no false connectivity) |
@@ -242,7 +248,8 @@ perspective, and reading what comes back honestly.
 7. **Honor the typed outcomes.** `underdetermined` refer → your ask to the
    user. `UNKNOWN` from `resolve` in a tracking world → "I don't know" is a
    representable, correct answer. `Materialization.unresolved` names the
-   frontier (thunks in scope) and `defaults` are coherence fills, not facts.
+   frontier (thunks in scope), `defaults` are coherence fills, not facts,
+   and `quantities` are derived totals, not stored ledger rows.
    Branch on these; don't coerce them into a guess.
 
 8. **Never cache derived truth host-side.** Location, emptiness, current

docs/LEXICON.md

@@ -18,6 +18,9 @@ The working vocabulary for pattern-buffer. One name per concept, used identicall
 | **`Frame`** | Perspective scope on every assertion: `canon`, `knows:<entity>`, named frames. Carries knowledge, contested truth, and privacy by structural absence. | RDF named-graph heritage; kept plain deliberately. |
 | **`Thunk`** | An explicitly unresolved aspect with a resolution policy. Forced exactly once; memoized forever. Thunks can move without resolving. | CS-canonical (lazy evaluation). |
 | **`frontier`** | The explicitly-unresolved region: the thunk table plus everything below the resolution floor. Where nothing has been established, the system serves no invented detail. | Robotics-canonical (occupancy-grid mapping); heritage is the lidar ingestion parallel. |
+| **`delta`** | A `value_type` for a signed numeric increment. It is admitted like any other row and only folds into totals for attributes declared `accrue`. | Plain math/database vocabulary. |
+| **`accrue`** | A fold policy for fungible quantities: latest absolute numeric baseline plus later signed deltas. | Accounting-canonical. |
+| **`quantity` / `ledger`** | The derived numeric total / the append-only rows that produced it. Totals surface through `FoldResult.quantity` and `Materialization.quantities`; the ledger remains ordinary assertions. | Plain accounting. |
 | **`Anchor`** | Composite identity signals on an entity: names/aliases, roles, recurring locations, distinguishing features. | Plain. |
 | **`Scene cursor`** | The ingest-time "where is the narrated action happening" pose. The largest single precision multiplier in ingestion. | Heritage: lidar pose estimation, not Trek. |
 | **`arch`** | The operator's inspection CLI: dump the buffer, query as-of, audit provenance — without touching the world. | Trek: "Computer, arch!" — the operator's control interface inside the simulation. Allowed in code as a tool nickname, not an API symbol. |

docs/WHITEPAPER.md

@@ -274,6 +274,7 @@ The complete write surface is small:
 ```
 assert(entity, kind)                      bring a thing into existence
 set(entity, attribute, value, …)          attach a fact (one assertion)
+delta(entity, attribute, signed_number)   append a numeric change for an accrue fold
 relate(subject, relation, object)         add an edge; for single-parent relations
                                           this IS the move operation (supersedes prior)
 event(kind, agents, patients, t, effects) reify an occurrence; effects are relates/sets
@@ -323,6 +324,13 @@ materialize(scope, as_of, frame, lens, budget) → materialization
 
 **Algorithm:** select in-scope, in-frame assertions valid at `as_of` per lens → fold STATE by supersession per (entity, attribute, frame) key — *per frame; a belief fold never overwrites canon* → walk the containment tree for the spatial spine, ordered by depth and salience → fill gaps from kind-defaults, every fill marked `default` → resolve forced thunks via the resolver (which feeds new assertions back through classification — the system is closed under its own operations) → shape to budget.
 
+**Numeric quantities:** an attribute may declare `fold_policy=accrue`. Its
+fold ignores durability and computes a derived total from the latest numeric
+`literal` baseline plus later signed `delta` rows. The total is served as a
+quantity, not as a stored assertion; the append-only ledger remains the audit
+trail. Integers and floats are supported in v1; exact decimal arithmetic is a
+future extension.
+
 **The budget invariant:** the CONSTITUTIVE spine is budget-exempt. Compress DISPOSITIONAL color, summarize peripheral STATE, digest EVENT chains — never compact identity and structure. (Anchored summarization with the anchor formally bound to the constitutive layer.)
 
 **Salience is a projection-time ranking, never a stored truth:** recency + reinforcement count + reference frequency + delta-from-baseline, computed from the log, cacheable in a derived index, never authoritative. Durability and salience are different axes: a fact unmentioned for three campaign-years has zero salience and full validity — ranked low until the drawer opens, then served at full confidence.

src/patternbuffer/classify.py

@@ -78,6 +78,8 @@ def __init__(
 
     def _guardrails(self, row: Assertion) -> tuple[str, float] | None:
         """Deterministic short-circuits. Return None to defer to the model."""
+        if row.value_type == "delta":
+            return STATE, 1.0
         if row.entity.startswith("event:") or row.attribute == "caused_by":
             return EVENT, 1.0
         if row.attribute in {"name", "alias"}:
@@ -274,9 +276,10 @@ def promote_accruals(self, threshold: int = 3) -> int:
             if (
                 row.entity.startswith("a:")
                 or row.entity.startswith(ATTR_PREFIX)
-                or row.value_type == "unresolved"
+                or row.value_type in ("unresolved", "delta")
+                or self._semantics.is_accrue(row.attribute)
             ):
-                continue
+                continue  # deltas / accrue quantities are summed, never a habit
             if self.durability(row.id) != STATE:
                 continue
             key = (row.entity, row.attribute, row.frame, repr(row.value))

src/patternbuffer/indexes.py

@@ -45,6 +45,8 @@ class FoldResult:
     corroborated_by: tuple[str, ...] = ()
     values: tuple = ()
     _value_rows: tuple[Assertion, ...] = field(default=(), repr=False, compare=False)
+    quantity: int | float | None = None
+    _ledger_rows: tuple[Assertion, ...] = field(default=(), repr=False, compare=False)
 
 
 @dataclass
@@ -128,6 +130,10 @@ def _values_agree(old: object, new: object) -> bool:
                 return True
         return False
 
+    @staticmethod
+    def _is_numeric(value: object) -> bool:
+        return isinstance(value, (int, float)) and not isinstance(value, bool)
+
     def _is_event_effect(self, row: Assertion, asserted_as_of: int | None) -> bool:
         """True iff the row carries a caused_by edge to an EVENT (spec §9.1)."""
         return bool(
@@ -162,6 +168,20 @@ def fold_key(
         if not candidates:
             return FoldResult(winner=None)
 
+        # Accrue reads raw numeric literal/delta rows (it filters to numbers
+        # internally and ignores unresolved/thunk machinery), so it branches
+        # before the thunk filter. Deltas are STATE by guardrail, never EVENT,
+        # so the gather-loop EVENT drop above leaves the ledger intact.
+        if self._semantics.is_accrue(attribute):
+            return self._fold_accrue(candidates)
+
+        # A `delta` on a NON-accrue attribute is not an absolute value — drop
+        # it before the thunk filter so it can neither suppress an unresolved
+        # placeholder nor compete in _fold_state.
+        candidates = [r for r in candidates if r.value_type != "delta"]
+        if not candidates:
+            return FoldResult(winner=None)
+
         # Resolution IS the supersession (whitepaper §8 — forcing memoizes
         # into the log; the fold serves the memo): a spent thunk (one with a
         # resolved_by marker) never competes, and once concrete rows exist
@@ -210,6 +230,42 @@ def fold_key(
             return FoldResult(winner=winner)
         return FoldResult(winner=None)
 
+    def _fold_accrue(self, rows: list[Assertion]) -> FoldResult:
+        """Accrue quantities: latest absolute numeric baseline plus later
+        signed numeric deltas. The ledger is provenance-only; the derived
+        quantity is surfaced separately from stored facts."""
+        def recency(row: Assertion) -> tuple[float, int]:
+            return (
+                row.valid_from if row.valid_from is not None else float("-inf"),
+                row.asserted_at,
+            )
+
+        literals = [
+            r for r in rows
+            if r.value_type == "literal" and self._is_numeric(r.value)
+        ]
+        deltas = [
+            r for r in rows
+            if r.value_type == "delta" and self._is_numeric(r.value)
+        ]
+        baseline = max(literals, key=recency) if literals else None
+        baseline_value: int | float = baseline.value if baseline is not None else 0
+        baseline_key = recency(baseline) if baseline is not None else None
+        contributing = [
+            r for r in deltas if baseline_key is None or recency(r) > baseline_key
+        ]
+        contributing.sort(key=recency)
+        if baseline is None and not contributing:
+            return FoldResult(winner=None)
+        total = baseline_value + sum(r.value for r in contributing)
+        winner = contributing[-1] if contributing else baseline
+        ledger_rows = ((baseline,) if baseline is not None else ()) + tuple(contributing)
+        return FoldResult(
+            winner=winner,
+            quantity=total,
+            _ledger_rows=ledger_rows,
+        )
+
     def _fold_set_valued(self, rows: list[Assertion]) -> FoldResult:
         """Set-valued keys accumulate current members instead of conflicting.
 

src/patternbuffer/ingest.py

@@ -54,7 +54,7 @@
                     "entity": {"type": "string"},
                     "attribute": {"type": "string"},
                     "value": {},
-                    "value_type": {"enum": ["entity", "literal", "unresolved"]},
+                    "value_type": {"enum": ["entity", "literal", "unresolved", "delta"]},
                     "frame": {"type": "string"},
                     "status": {"enum": ["stated", "observed", "inferred", "assumed"]},
                     "timeless": {"type": "boolean"},

src/patternbuffer/model.py

@@ -60,7 +60,7 @@
 SET_VALUED_ATTRIBUTES = frozenset({"name", "alias", "connects_to", "adjacent_to",
                                    "maybe_same_as", "same_as"})
 
-VALUE_TYPES = frozenset({"entity", "literal", "unresolved"})
+VALUE_TYPES = frozenset({"entity", "literal", "unresolved", "delta"})
 
 CANON = "canon"