external-integration

57 beliefs (32 IN, 25 OUT)

The external-integration topic covers how the Truth Maintenance System ingests, reconciles, and maintains beliefs that originate outside the system, primarily through agent import and sync operations. This matters because a TMS that only manages internally-created beliefs is limited in scope; real-world knowledge bases need to absorb information from other agents and external sources while preserving their internal consistency guarantees. The active beliefs in this topic divide into two tiers: concrete implementation-level facts about how import and sync actually work, and a small number of higher-level claims about lifecycle completeness and governance.

At the implementation level, the system offers two distinct reconciliation strategies (import-sync-has-dual-reconciliation-modes). Import mode is additive and skips existing nodes (import-skips-existing-sync-is-remote-wins), while sync mode implements remote-wins semantics, overwriting local text and truth values and retracting beliefs removed from the remote source (sync-is-remote-wins). Both modes share critical safety mechanisms: a two-phase truth maintenance process that adds all nodes before propagating truth values and applying retractions (import-two-phase-truth-maintenance, import-ordering-ensures-correct-final-state), topological sorting that gracefully tolerates dependency cycles rather than crashing (import-topo-sort-cycle-tolerant, import-agent-topo-sort-breaks-cycles), and normalization that silently drops references to unknown IDs to prevent dangling edges (normalization-drops-unknown-refs). OUT or STALE beliefs are imported without justifications to prevent recompute from incorrectly resurrecting them (out-beliefs-imported-without-justifications). Claims whose dependencies are entirely absent from the import set become premises, defaulting to IN (external-deps-become-premises). The parser is forward-compatible, silently skipping unknown metadata fields (import-beliefs-parser-is-forward-compatible), and API functions always parse files into structured data before delegating to the database layer (import-functions-parse-before-dispatch).

The sync subsystem has several verified operational properties: it is idempotent, producing zero changes on repeated calls with identical data (sync-agent-is-idempotent), it preserves cascade wiring so that kill-switch retractions still propagate correctly after sync (sync-agent-preserves-cascade-structure, sync-preserves-cascade-wiring), it returns structured diff counts for accurate accounting (sync-returns-structured-diff-counts), and calling sync for the first time on a new agent produces identical results to import (sync-agent-first-sync-equals-import). These properties together make sync safe for automated, scheduled reconciliation (sync-is-safe-for-automated-reconciliation). At the lifecycle level, the system tracks external beliefs from ingestion through ongoing validity monitoring, including staleness detection for source drift (external-belief-lifecycle-is-complete, external-lifecycle-is-complete-and-automatically-maintained), operating within a metadata-enabled governance framework (external-lifecycle-operates-within-rich-governance).

A striking feature of this topic is the large number of OUT beliefs, nearly all of which are higher-level derived claims about external beliefs achieving "full parity," "total integration," or "complete invariant equivalence" with internal beliefs. Claims like external-beliefs-achieve-total-integration, external-beliefs-are-invariant-equivalent, and external-integration-preserves-all-invariants have all been retracted, along with intermediate claims about defensive containment, bidirectional bounding, and trust-bounded verification. This pattern suggests that while the concrete implementation mechanisms for import and sync are well-established and verified, the broader architectural claims about external beliefs being fully equivalent to internal beliefs did not survive scrutiny. The system demonstrably handles external belief ingestion and reconciliation robustly, but the retracted beliefs indicate that earlier claims about complete parity across all quality dimensions, invariant guarantees, and containment layers were overstated or could not be justified from the available evidence.

OUT external-belief-ingestion-is-defensively-layered
External beliefs enter the system through defensively-layered pipelines regardless of source: LLM derivation applies fail-soft validation, Jaccard retraction guards, and environment isolation, while agent import provides dual reconciliation modes with heterogeneous truth state handling — both converge on the same underlying mutation infrastructure.
IN external-belief-lifecycle-is-complete
The system manages external beliefs across their full lifecycle: import/sync provides dual reconciliation modes with heterogeneous truth state handling and namespace auto-wiring, while staleness checking detects source drift for CI gating — beliefs are tracked from initial ingestion through ongoing validity monitoring.
OUT external-belief-management-is-complete
External beliefs are managed across their entire lifecycle with no gap between any management phase: safely integrated through defensive validation pipelines, lifecycle-managed across dual import/sync reconciliation modes, and actively kept current through staleness detection and derive pipeline refresh — providing complete external belief management from ingestion through retirement.
OUT external-beliefs-achieve-integration-parity
External beliefs achieve full parity with internal beliefs: they are managed across their complete lifecycle with no gap between any management phase AND participate in the same deterministic revision engine as all other belief origins — external provenance is a property of ingestion, not of ongoing maintenance.
OUT external-beliefs-achieve-total-integration
External beliefs achieve total integration along all quality axes simultaneously: grounded across every invariant dimension (origin, time, structure), participating in all correction mechanisms with full auditability, and fully equivalent to internal beliefs — no property distinguishes external from internal.
OUT external-beliefs-are-correctable-and-invariant-equivalent
External beliefs achieve full parity along two independent quality axes: invariant equivalence ensures they participate in the same consistency guarantees as internal beliefs, while origin-spanning auditability ensures they are fully correctable with complete traceable history.
OUT external-beliefs-are-defended-and-lifecycle-managed
External beliefs are managed end-to-end across a complete trust boundary: defensively contained at ingestion through layered validation pipelines and namespace isolation, then actively lifecycle-managed through dual reconciliation modes, staleness detection against source material, and CI gating — no phase of external belief existence lacks oversight.
OUT external-beliefs-are-fully-invariant-grounded
External beliefs achieve complete invariant equivalence with internal beliefs, and those invariants are anchored along all three dimensions — origin, temporal, and structural — meaning external integration participates in the system's deepest invariant guarantees, not merely surface-level safety.
OUT external-beliefs-are-invariant-equivalent
External beliefs achieve complete equivalence with internal beliefs at every system level: they participate in identical invariant-preserving revision systems and achieve full behavioral integration parity — the system provides no mechanism to distinguish external from internal beliefs in terms of protection or management.
OUT external-beliefs-are-safe-and-current
External beliefs are managed end-to-end across their complete lifecycle with no gap between ingestion safety and ongoing maintenance: defensively contained at ingestion through layered validation, correctly lifecycle-managed through import reconciliation and staleness checking, and actively tracked for currency — no external belief enters unvalidated, drifts undetected, or persists without lifecycle oversight.
OUT external-beliefs-defensively-contained
External beliefs pass through two independent safety layers: defensive ingestion pipelines (fail-soft validation, Jaccard guards, dual import/sync reconciliation modes) filter and validate beliefs on entry, while the self-contained agent subsystem (namespace isolation, relay-pair kill-switches, reversible lifecycle management) constrains their operational footprint after ingestion.
IN external-deps-become-premises
A claim whose `depends_on` references are all absent from the beliefs file gets no justifications and is added as a premise (IN by default).
OUT external-ingestion-is-format-resilient-and-defensively-layered
External belief ingestion achieves both defensive containment (fail-soft validation, Jaccard retraction guards, dual import/sync reconciliation, namespace isolation) AND format resilience (parser version fallback, forward-compatible metadata parsing, prose-tolerant JSON extraction), ensuring robust integration even as external source formats evolve unpredictably.
OUT external-ingestion-is-resilient-and-convergent
External belief ingestion achieves end-to-end reliability through two complementary properties: format resilience absorbs syntactic variation at the parsing boundary (dual parser versions, schema migration tolerance, prose-tolerant JSON extraction with defensive layering), while deterministic convergence ensures consistent final state through fixpoint reconciliation regardless of input ordering or repeated application.
OUT external-inputs-face-defense-in-depth
External beliefs face defense in depth across two independent containment layers: input-level containment (defensive validation pipelines, agent namespace isolation) prevents bad data from entering, while system-level containment (architectural layer boundaries, lifecycle-aware checking and propagation) prevents bad data from persisting or spreading.
OUT external-integration-is-architecturally-safe
External beliefs are end-to-end safe within the system's architecture: defensively contained at ingestion and lifecycle-managed thereafter (external belief thread) within the same three-layer boundaries and atomic mutation guarantees that protect internal operations (architecture thread).
OUT external-integration-is-hardened-and-boundary-controlled
LLM integration achieves production-grade robustness (bounded execution, fail-soft error handling, process isolation, fault tolerance) while information boundaries are controlled at every level (authorization gating, budget constraints, defensive ingestion) — the system neither leaks sensitive information outward nor admits unvalidated beliefs inward.
OUT external-integration-preserves-all-invariants
External beliefs are architecturally safe at ingestion and participate in the same invariant-preserving revision system as all other belief origins — architectural containment and revision parity together ensure external integration cannot corrupt system invariants.
OUT external-interface-is-bidirectionally-bounded
The system's interaction with external systems is bounded in both directions: output is budget-limited through accurate token estimation ensuring context windows are respected, and input drift is comprehensively detected through staleness checking — no unbounded data flows cross the system boundary.
OUT external-lifecycle-achieves-topology-accurate-quality
External beliefs receive quality-complete self-correction that operates on accurate convergent topology — every correction to an externally-originated belief propagates through verified dependency structure with complete fidelity, ensuring external belief quality is maintained with the same topological accuracy as internal beliefs.
IN external-lifecycle-is-complete-and-automatically-maintained
External beliefs achieve both complete lifecycle management (dual reconciliation modes with heterogeneous truth state handling and staleness detection) and automated ongoing maintenance (idempotent sync with cascade preservation and full source staleness coverage), enabling zero-touch external belief management
OUT external-lifecycle-is-deterministic-and-trust-bounded
External beliefs follow a fully deterministic lifecycle from ingestion through ongoing maintenance, enclosed within verified trust boundaries at every phase: structural verification with trust-bounded bidirectional flow control at the perimeter, and deterministic architecturally-grounded lifecycle management governing internal state trajectories.
IN external-lifecycle-operates-within-rich-governance
External beliefs achieve complete automated lifecycle management within a metadata-enabled source-grounded governance framework — creation, reconciliation, staleness detection, and ongoing maintenance all operate under rich governance extending beyond binary truth values to structured lifecycle state.
OUT external-lifecycle-receives-quality-complete-self-correction
External beliefs follow deterministic trust-bounded lifecycles AND receive self-correction that is complete across all quality dimensions — grounded in source integrity, documented with referenceable artifacts, convergent on accurate topology, and evolution-tolerant — ensuring external beliefs are not merely contained but actively maintained at the same quality standard as internal beliefs.
OUT external-surface-is-fully-controlled
The system's external surface is fully controlled along independent axes: bidirectional bounds constrain output size (token budgets) and input quality (staleness detection), while defensive containment layers (validation pipelines, namespace isolation) prevent external beliefs from violating internal invariants.
OUT external-surface-is-verified-and-trust-bounded
The complete external-facing surface achieves both structural verification (pure delegation with hermetic tests and fault tolerance across all information paths) and comprehensive trust enforcement (architectural self-containment with information flow control at every boundary) — no external interaction bypasses either the verification chain or trust controls.
OUT external-surface-is-verified-trust-bounded-and-bidirectionally-controlled
The system's complete external perimeter achieves defense-in-depth through three independently-established properties: structural verification (pure delegation with hermetic tests), trust boundaries (self-containment and defensive ingestion), and bidirectional flow control (token budgets constraining output, hardened LLM integration constraining input) — no external interaction bypasses all three layers.
OUT import-achieves-ordered-convergent-reconciliation
Import achieves correct final state through two reinforcing mechanisms: deliberate ordering discipline (add → propagate → retract) ensures deferred retractions don't corrupt intermediate states, while deterministic convergence (dual reconciliation modes reaching stable states, propagation terminating via fixpoint) ensures the result is unique and reproducible regardless of input ordering within each phase.
IN import-agent-topo-sort-breaks-cycles
`_topo_sort_claims` breaks dependency cycles by appending all remaining unsorted nodes after `max_passes = len(remaining) + 1` iterations rather than raising an error, ensuring import always completes.
IN import-beliefs-nogood-id-uses-high-water-mark
`_next_nogood_id` is set to `max(current, parsed_id + 1)` during import, preventing future auto-generated nogood IDs from colliding with imported ones.
IN import-beliefs-parser-is-forward-compatible
Unknown `- ` metadata lines in belief markdown are silently skipped via a `pass` branch, making the parser forward-compatible with new export format fields.
IN import-functions-parse-before-dispatch
API import functions (`import_json`, `import_beliefs`, `import_agent`) read and parse files into structured data in the API layer before delegating to `PgApi` — PgApi never receives raw file paths
IN import-handles-heterogeneous-truth-states
The import pipeline handles mixed truth states: OUT/STALE beliefs arrive without justifications, topological sort tolerates cycles, and two-phase truth maintenance reconciles everything post-import
IN import-json-uses-topological-sort
`api.import_json()` reconstructs networks via a multi-pass topological sort loop — repeatedly adding nodes whose dependencies are already loaded — with a force-add fallback for cycles or missing deps.
IN import-ordering-ensures-correct-final-state
Import follows a deliberate ordering discipline — add nodes first, propagate truth values second, apply explicit retractions last — ensuring deferred retractions correctly override any truth values that propagation would compute, producing a final state that respects both structural dependencies and explicit intent.
IN import-paths-bump-nogood-counter
Both `import_json` and `import_into_network` update `_next_nogood_id` to at least `max_imported_id + 1`, ensuring imported nogoods with explicit IDs don't create future collisions
IN import-provides-complete-reconciliation
The import subsystem provides complete reconciliation coverage: heterogeneous truth states are handled correctly on initial load, dual modes support additive import and remote-wins sync for different operational needs, and the colon-based namespace convention with auto-wiring prevents ID collisions across agents.
OUT import-reconciliation-converges-deterministically
Import reconciliation achieves both completeness and convergence: dual import/sync modes handle heterogeneous truth states with namespace isolation and topological cycle tolerance (completeness), while all reconciliation operations — individual propagation, agent sync, and global recompute — converge to deterministic fixed points on repeated application (convergence), ensuring that import never introduces oscillation or nondeterminism.
IN import-skips-existing-sync-is-remote-wins
Import mode (`import_agent`) is a one-time load that skips existing nodes; sync mode updates text/justifications/truth values with remote-wins semantics and retracts locally any beliefs removed from the remote
IN import-sync-has-dual-reconciliation-modes
The import/sync subsystem offers two distinct reconciliation strategies: import is additive (skips existing nodes), while sync is remote-wins (overwrites text, justifications, and truth values from the remote source).
IN import-topo-sort-cycle-tolerant
Topological sorting of imported claims is best-effort: cycles cause remaining nodes to be appended in arbitrary order rather than raising an error, a pragmatic choice that avoids crashing on circular references.
IN import-topo-sort-tolerates-cycles
`_topo_sort_claims` attempts topological ordering but appends remaining nodes when progress stalls, gracefully handling dependency cycles instead of erroring
IN import-two-phase-truth-maintenance
Import/sync adds all nodes first, then runs `recompute_all()` to propagate truth values, then performs explicit retractions — this ordering prevents incorrect cascades from partially-constructed networks
IN normalization-drops-unknown-refs
Both `_normalize_markdown` and `_normalize_json` silently drop antecedent/outlist references to IDs not present in the import set, preventing dangling edges in the dependency graph.
IN out-beliefs-imported-without-justifications
Beliefs that are OUT or STALE in the source are imported with an empty justification list, preventing `recompute_all` from resurrecting them to IN
IN sync-agent-first-call-equals-import
Calling `sync_agent` for an agent with no prior import produces identical results to `import_agent`, including all node creation and namespace wiring
IN sync-agent-first-sync-equals-import
When no prior import exists for an agent, `sync_agent` behaves identically to `import_agent` — creating the `agent:active` premise and returning `created_premise: True` — rather than requiring a separate import step.
IN sync-agent-idempotent
Two consecutive `sync_agent` calls with identical file content produce zero additions, removals, and updates on the second call
IN sync-agent-is-idempotent
Calling `sync_agent` twice with identical data produces the same database state; the second call returns zero adds, removes, and updates — a no-op by design.
IN sync-agent-preserves-cascade-structure
After `sync_agent` completes, the agent's outlist-based justification structure remains intact — revoking `agent:active` still cascades all agent beliefs to OUT, proving sync does not corrupt kill-switch wiring.
IN sync-agent-remote-wins
Duplicates existing belief `sync-is-remote-wins`
IN sync-agent-returns-count-dict
`sync_agent` returns a dict with keys `beliefs_added`, `beliefs_removed`, `beliefs_updated`, and `beliefs_unchanged` for accurate accounting of what changed
IN sync-is-remote-wins
`_sync_claims` implements remote-wins reconciliation: remote text/metadata overwrites local, beliefs removed from remote are retracted locally, and beliefs remotely IN but locally OUT are re-asserted
IN sync-is-safe-for-automated-reconciliation
`sync_agent` can be safely re-run on any schedule — idempotent execution with cascade structure preservation means repeated automated synchronization never corrupts outlist-based justification hierarchies or produces accumulating side effects.
IN sync-preserves-cascade-wiring
After `sync_agent` runs, the `agent:inactive` outlist entries on beliefs are preserved, so retracting `agent:active` still cascades all agent beliefs to OUT
IN sync-registers-agent-repo-path
`sync_agent` records the agent's source file path in the repo registry (`list_repos`), enabling the system to track which file each agent's beliefs originated from.
IN sync-returns-structured-diff-counts
`sync_agent` returns a dict with `beliefs_added`, `beliefs_updated`, `beliefs_unchanged`, and `beliefs_removed` counts that accurately reflect the diff between remote file and local state — no double-counting across sync cycles.