compact-module

31 beliefs (22 IN, 9 OUT)

The compact module is the subsystem responsible for distilling a belief network into a budget-constrained markdown string suitable for inclusion in context-limited pipelines. It operates as a pure function with no side effects, no I/O, and no mutation of the underlying network (compact-is-pure-function, compact-pure-function), and it is designed to be infallible, gracefully handling edge cases like empty networks, zero budgets, and missing metadata without raising exceptions (compact-is-infallible). The module's output is organized into three priority-ordered sections — nogoods first, then OUT (retracted) nodes, then IN (active) nodes — where earlier sections are never displaced by later ones (compact-priority-order, compact-priority-order-is-nogoods-out-in, compact-three-sections). Within the IN section, nodes are sorted by descending dependent count so that structurally important beliefs survive budget truncation (compact-in-nodes-ordered-by-dependents). A footer reporting token usage is pre-reserved before any section begins filling, guaranteeing auditability metadata always appears (compact-footer-pre-reserved, compact-self-reports-tokens).

Budget enforcement relies on an efficient but approximate strategy. Token estimation uses a simple chars/4 heuristic rather than word counting or an external tokenizer (compact-estimate-tokens-chars-div-4), and per-line budget checks run in O(1) time via a running character count (compact-char-tracking-o1, compact-budget-tracking-is-efficient-and-approximate). Crucially, the budget is a soft cap, not a hard guarantee — structural overhead such as section headers and truncation messages can cause actual output to overshoot the specified budget by up to roughly 25% (compact-budget-is-soft-cap, compact-budget-soft-ceiling). An earlier belief (compact-never-exceeds-budget) asserts a strict guarantee, creating a tension with the soft-cap beliefs that the network has not fully resolved. Additional features include summary-node elision, where IN nodes covered by a summary node are hidden from output to reduce redundancy, provided the summary itself remains IN (compact-summary-nodes-hide-covered, compact-summary-hiding-requires-in), and surfacing of stale-reason metadata on OUT nodes (compact-surfaces-stale-reason-metadata). The Postgres-backed API layer wraps this with access-tag filtering via visible_to (pg-compact-generates-budget-constrained-markdown).

The retracted beliefs tell an important story about how understanding of the module evolved. Several ambitious composite claims — that compact is simultaneously deterministic, bounded, and structurally complete (compact-is-deterministic-pure-and-bounded, compact-is-efficient-deterministic-and-bounded, compact-is-predictable-bounded-distillation, compact-output-is-structurally-complete-and-predictably-bounded) — were retracted because the "bounded" component turned out to be only approximately true. The discovery that structural overhead can cause meaningful budget overshoot invalidated any claim of hard guarantees. Similarly, compact-token-estimate-is-word-count was retracted once the actual chars/4 mechanism was identified. The broader system-level claim (system-output-is-complete-bounded-and-ci-ready) fell for the same reason. What survives is a more honest characterization: the compact module is pure, deterministic, priority-ordered, and infallible, with budget enforcement that is computationally efficient and practically effective but approximate rather than mathematically strict. The network also contains a few acknowledged duplicates (compact-sorts-by-dependents, compact-sorts-in-nodes-by-dependents-descending) that mirror compact-in-nodes-ordered-by-dependents.

OUT compact-budget-controls-output-size
The compact module's token budget reliably constrains total output size
OUT compact-budget-guarantee
`compact()` output estimated token count never exceeds the `budget` parameter; every line is gated by `_over_budget` before appending.
IN compact-budget-is-soft-cap
The compact token budget is approximate; structural overhead (section headers, truncation messages) can cause up to ~25% overshoot beyond the specified budget.
OUT compact-budget-only-limits-in-nodes
The token budget only constrains the IN nodes section; nogoods and OUT nodes are always emitted regardless of budget, so compact output can exceed the specified budget value.
IN compact-budget-soft-ceiling
The `compact` function treats the token budget as approximate; structural overhead (headers, truncation messages) can cause output to exceed the budget by up to ~25%.
IN compact-budget-tracking-is-efficient-and-approximate
The compact module tracks token budgets efficiently through an approximate but computationally fast strategy: O(1) per-line budget checks via a running character count, with token estimation based on chars/4 — a lightweight approximation avoiding external tokenizer dependencies while maintaining accuracy sufficient for budget enforcement.
IN compact-char-tracking-o1
Budget tracking uses a running `_char_count` integer, making per-line budget checks O(1) instead of O(n).
IN compact-estimate-tokens-chars-div-4
`estimate_tokens` uses `len(text) // 4` with a floor of 1, not word count or any external tokenizer.
IN compact-footer-pre-reserved
The footer line's token cost is pre-computed and reserved before any section starts filling, guaranteeing it always fits within the budget.
IN compact-in-nodes-ordered-by-dependents
IN nodes are sorted by descending dependent count so structurally important nodes (those depended on by many others) are emitted first and survive budget truncation.
OUT compact-is-deterministic-pure-and-bounded
The compact module produces output that is simultaneously deterministic (pure function with fixed priority ordering), bounded (guaranteed to never exceed the token budget), and self-describing (includes its own token count for auditability).
OUT compact-is-efficient-deterministic-and-bounded
The compact module simultaneously achieves computational efficiency (O(1) per-line budget tracking via running character count with chars/4 token estimation), mathematical determinism (pure function with no side effects), and guaranteed output bounds (never exceeds the budget parameter) — all three desirable output properties without trade-offs.
IN compact-is-infallible
`compact()` handles empty networks, zero-budget, and missing metadata without raising exceptions — designed to always produce a valid string.
OUT compact-is-predictable-bounded-distillation
The compact module is a fully predictable information distillation: a pure function with deterministic priority ordering that reliably constrains output within token budgets, self-reports resource usage, and structurally important nodes are prioritized through dependent-count sorting
IN compact-is-pure-function
`compact()` performs no I/O, no database access, no mutations, and no side effects; it is a pure transformation from `Network` to `str`.
IN compact-never-exceeds-budget
`compact()` guarantees the returned string's estimated token count (chars/4) does not exceed the `budget` parameter, enforced by pre-checking every line addition against remaining space.
OUT compact-output-is-structurally-complete-and-predictably-bounded
The compact module simultaneously achieves structural completeness — priority-ordered sections where later sections never displace earlier ones, infallible handling of all edge cases including empty networks and zero budgets, and pre-reserved footer guaranteeing auditability metadata — and predictable resource bounding through a pure deterministic function with guaranteed budget enforcement and self-reporting token counts, making compact a reliable building block for automated context-limited pipelines.
IN compact-priority-order
Sections are emitted in fixed order: nogoods, OUT nodes, IN nodes; a later section never displaces content from an earlier one.
IN compact-priority-order-is-nogoods-out-in
Sections are emitted in strict priority order: nogoods first, then OUT nodes, then IN nodes; if the budget is exhausted early, lower-priority sections are entirely omitted.
IN compact-pure-function
`compact()` has no side effects, performs no I/O, and does not mutate the `Network` instance.
IN compact-self-reports-tokens
When given a budget, the `compact` output includes a `Token count: N / B budget` line for auditability.
IN compact-sorts-by-dependents
Duplicate of existing `compact-in-nodes-ordered-by-dependents`.
IN compact-sorts-in-nodes-by-dependents-descending
Duplicates existing belief `compact-in-nodes-ordered-by-dependents`.
IN compact-structure-is-priority-ordered-and-infallible
The compact module produces output with deterministic priority-ordered sections (nogoods, OUT, IN) and handles all edge cases (empty networks, zero budget, missing metadata) without raising exceptions, with footer space pre-reserved before section filling begins.
IN compact-summary-hiding-requires-in
A summary node only hides its covered nodes when the summary itself is IN; if the summary goes OUT, covered nodes reappear in the compact output.
IN compact-summary-nodes-hide-covered
IN nodes whose IDs appear in another node's `summarizes` metadata list are excluded from compact output to avoid redundancy; the hidden count is reported.
IN compact-surfaces-stale-reason-metadata
OUT nodes with `stale_reason` in their metadata include the reason string in the compact output.
IN compact-three-sections
The `compact` output is organized into three markdown sections: `## IN (active)`, `## OUT (retracted)`, and `## Nogoods`, each present only when the network contains nodes of that type.
OUT compact-token-estimate-is-word-count
`estimate_tokens` counts whitespace-separated words, not BPE tokens; the budget parameter throughout the compact module is measured in this unit.
IN pg-compact-generates-budget-constrained-markdown
`PgApi.compact()` produces a markdown summary of the belief network constrained by a token budget, filtered by `visible_to` access tags, sorted by dependent count, with summary-node elision and nogood inclusion
OUT system-output-is-complete-bounded-and-ci-ready
The system's two primary output mechanisms — compact belief summaries and staleness reports — both meet production standards: structurally complete with priority ordering, predictably bounded by token budgets, and CI-pipeline ready with deterministic sorted output, nonzero exit codes, and machine-parseable schemas.