cairn-engine 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (42) hide show
  1. cairn_engine-0.1.0/.gitignore +36 -0
  2. cairn_engine-0.1.0/LICENSE +21 -0
  3. cairn_engine-0.1.0/PKG-INFO +105 -0
  4. cairn_engine-0.1.0/README.md +83 -0
  5. cairn_engine-0.1.0/intents/cross_system_index_intent.yaml +129 -0
  6. cairn_engine-0.1.0/intents/entity_bitemporal_intent.yaml +186 -0
  7. cairn_engine-0.1.0/intents/entity_resolution_intent.yaml +209 -0
  8. cairn_engine-0.1.0/intents/entity_semantic_intent.yaml +155 -0
  9. cairn_engine-0.1.0/intents/entity_traversal_intent.yaml +176 -0
  10. cairn_engine-0.1.0/intents/graph_backend_intent.yaml +173 -0
  11. cairn_engine-0.1.0/intents/ontology_authoring_intent.yaml +210 -0
  12. cairn_engine-0.1.0/intents/sqlite_adapter_intent.yaml +138 -0
  13. cairn_engine-0.1.0/pyproject.toml +39 -0
  14. cairn_engine-0.1.0/src/cairn_engine/__init__.py +97 -0
  15. cairn_engine-0.1.0/src/cairn_engine/adapters/__init__.py +10 -0
  16. cairn_engine-0.1.0/src/cairn_engine/adapters/_build.py +87 -0
  17. cairn_engine-0.1.0/src/cairn_engine/adapters/base.py +78 -0
  18. cairn_engine-0.1.0/src/cairn_engine/adapters/cypher.py +127 -0
  19. cairn_engine-0.1.0/src/cairn_engine/adapters/jsonfile.py +122 -0
  20. cairn_engine-0.1.0/src/cairn_engine/adapters/memory.py +188 -0
  21. cairn_engine-0.1.0/src/cairn_engine/adapters/sqlite.py +187 -0
  22. cairn_engine-0.1.0/src/cairn_engine/entity/__init__.py +12 -0
  23. cairn_engine-0.1.0/src/cairn_engine/entity/bitemporal.py +101 -0
  24. cairn_engine-0.1.0/src/cairn_engine/entity/crosssystem.py +128 -0
  25. cairn_engine-0.1.0/src/cairn_engine/entity/model.py +100 -0
  26. cairn_engine-0.1.0/src/cairn_engine/entity/normalize.py +55 -0
  27. cairn_engine-0.1.0/src/cairn_engine/entity/ontology.py +366 -0
  28. cairn_engine-0.1.0/src/cairn_engine/entity/resolve.py +271 -0
  29. cairn_engine-0.1.0/src/cairn_engine/entity/semantic.py +103 -0
  30. cairn_engine-0.1.0/src/cairn_engine/entity/traverse.py +107 -0
  31. cairn_engine-0.1.0/src/cairn_engine/py.typed +0 -0
  32. cairn_engine-0.1.0/tests/integration/test_blog_graph_e2e.py +117 -0
  33. cairn_engine-0.1.0/tests/unit/test_adapters.py +122 -0
  34. cairn_engine-0.1.0/tests/unit/test_bitemporal.py +172 -0
  35. cairn_engine-0.1.0/tests/unit/test_cross_system.py +134 -0
  36. cairn_engine-0.1.0/tests/unit/test_cypher.py +189 -0
  37. cairn_engine-0.1.0/tests/unit/test_ontology.py +287 -0
  38. cairn_engine-0.1.0/tests/unit/test_resolve.py +276 -0
  39. cairn_engine-0.1.0/tests/unit/test_scaffold.py +58 -0
  40. cairn_engine-0.1.0/tests/unit/test_semantic.py +156 -0
  41. cairn_engine-0.1.0/tests/unit/test_sqlite_adapter.py +124 -0
  42. cairn_engine-0.1.0/tests/unit/test_traverse.py +167 -0
@@ -0,0 +1,36 @@
1
+ # Python
2
+ __pycache__/
3
+ *.py[cod]
4
+ *.egg-info/
5
+ .eggs/
6
+ build/
7
+ dist/
8
+ *.so
9
+
10
+ # venv / uv
11
+ .venv/
12
+ .uv/
13
+ uv.lock
14
+
15
+ # tooling caches
16
+ .pytest_cache/
17
+ .mypy_cache/
18
+ .ruff_cache/
19
+ .coverage
20
+ htmlcov/
21
+
22
+ # editors / os
23
+ .vscode/
24
+ .idea/
25
+ .DS_Store
26
+
27
+ # local scratch / data (never commit real corpora)
28
+ *.db
29
+ *.sqlite
30
+ *.parquet
31
+ scratch/
32
+ tmp/
33
+
34
+ # user corpora (never ship user content in the library repo)
35
+ corpus/
36
+ examples/graph.svg # generated by graph_visualize.py — contains user corpus content
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Leo Celis
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,105 @@
1
+ Metadata-Version: 2.4
2
+ Name: cairn-engine
3
+ Version: 0.1.0
4
+ Summary: Deterministic entity / world-model engine for AI agents — resolve messy references to canonical IDs, traverse relations, author the alias table. Storage-agnostic, local-first, zero generative-LLM on the hot path.
5
+ Project-URL: Homepage, https://github.com/leocelis/cairn
6
+ Project-URL: Source, https://github.com/leocelis/cairn
7
+ Project-URL: Issues, https://github.com/leocelis/cairn/issues
8
+ Author-email: Leo Celis <hello@leocelis.com>
9
+ License-Expression: MIT
10
+ License-File: LICENSE
11
+ Keywords: ai-agents,deterministic,entity-resolution,knowledge-graph,local-first,retrieval
12
+ Classifier: Development Status :: 3 - Alpha
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: License :: OSI Approved :: MIT License
15
+ Classifier: Programming Language :: Python :: 3.11
16
+ Classifier: Programming Language :: Python :: 3.12
17
+ Classifier: Programming Language :: Python :: 3.13
18
+ Classifier: Topic :: Software Development :: Libraries
19
+ Classifier: Typing :: Typed
20
+ Requires-Python: >=3.11
21
+ Description-Content-Type: text/markdown
22
+
23
+ # cairn-engine
24
+
25
+ **The deterministic entity / world-model engine for AI agents.** (The brand is
26
+ **Cairn**; the distribution is `cairn-engine` and the import package is
27
+ `cairn_engine`.)
28
+
29
+ Resolve messy human references to stable canonical IDs, traverse their relations
30
+ bi-temporally, and author the frozen alias table that makes it all reproducible —
31
+ storage-agnostic, local-first, **zero generative-LLM and zero network on the
32
+ default path**, **zero runtime dependencies** (pure stdlib).
33
+
34
+ `cairn-engine` is the foundational entity subsystem. The agent-retrieval layer
35
+ (gate, signals, fusion, assembler) lives in the separate
36
+ [`cairn-retrieval`](https://github.com/leocelis/cairn/tree/main/packages/cairn-retrieval)
37
+ package, which depends on this one.
38
+
39
+ > **Status:** feature-complete, pre-release (0.1.0) — full resolution cascade,
40
+ > bounded bi-temporal traversal, ontology authoring + 3-tier dedup, SQLite and
41
+ > openCypher adapters, and a cross-system entity index. 120 tests, ruff + mypy
42
+ > strict, byte-stable. The retrieval-quality benchmark (OP-31) is the next phase;
43
+ > until then, treat determinism/portability as proven and quality as unclaimed.
44
+ > See the [roadmap](https://github.com/leocelis/cairn/blob/main/ROADMAP.md).
45
+
46
+ ## Install
47
+
48
+ ```bash
49
+ pip install cairn-engine
50
+ ```
51
+
52
+ ## Quickstart
53
+
54
+ ```python
55
+ from cairn_engine import (
56
+ Entity, InMemoryAliasTable, InMemoryGraph, Ref, Relation, resolve, traverse,
57
+ )
58
+
59
+ entities = [
60
+ Entity("account::schwab_main", "Schwab", "config", aliases=("my Schwab account",),
61
+ refs=(Ref(doc_id="doc::accounts"),)),
62
+ Entity("doc::payment_retry_policy", "Payment Retry Policy", "document",
63
+ refs=(Ref(doc_id="doc::retry"),),
64
+ relations=(Relation("references", "account::schwab_main"),)),
65
+ ]
66
+
67
+ table = InMemoryAliasTable.from_entities(entities) # build -> freeze -> read-only
68
+ graph = InMemoryGraph.from_entities(table.canonical_entities())
69
+
70
+ resolved, unresolved = resolve("does the payment retry policy touch my Schwab account?",
71
+ table=table)
72
+ # both entities found by gazetteer scan; unresolved == [] (a miss is never a made-up ID)
73
+
74
+ result = traverse(resolved[0].canonical_id, graph=graph, depth=2)
75
+ # connected DocumentRefs, hop-scored 1/(1+hop), byte-stable
76
+ ```
77
+
78
+ The resolution cascade: **exact → normalized (NFKC) → fuzzy (token-sort ≥ 0.85,
79
+ entropy-gated) → semantic (opt-in: your embedder) → LLM arbiter (opt-in: your
80
+ callable; picks among presented candidates in the 0.70–0.85 band — never mints an
81
+ ID)**. Misses come back in `unresolved` — never a synthesized ID (closed world).
82
+
83
+ Build-time authoring (offline, human-gated): `author_from_text` →
84
+ `dedup_candidates` (exact → MinHash/LSH → review band, never auto-merged) → your
85
+ approval → `freeze()`. Optional extractors (GLiNER / LLM) enter as callables you
86
+ supply — the engine never imports third-party packages or calls APIs.
87
+
88
+ Also here: bi-temporal state (`as_at`, `supersede`), a cross-system entity index
89
+ (`CrossSystemIndex`), a SQLite alias-table backend, and an openCypher compiler
90
+ (`compile_traversal` / `traverse_cypher`) that runs the same bounded traversal on
91
+ Neo4j / FalkorDB — the engine imports no DB driver; you pass the connection.
92
+
93
+ ## Design foundations
94
+
95
+ Grounded in five CS theories (canonicalization over equivalence classes, labeled
96
+ property graphs, the bi-temporal model, bounded transitive closure, and the
97
+ closed-world assumption) — see
98
+ [`docs/patterns/`](https://github.com/leocelis/cairn/tree/main/docs/patterns) and
99
+ [`docs/research/foundations/`](https://github.com/leocelis/cairn/tree/main/docs/research/foundations).
100
+ Every module is developed intent-first ([IVD](https://ivdframework.dev)):
101
+ constraints in `intents/` map 1:1 to tests with hand-computed golden fixtures.
102
+
103
+ ## License
104
+
105
+ MIT — Copyright (c) 2026 Leo Celis
@@ -0,0 +1,83 @@
1
+ # cairn-engine
2
+
3
+ **The deterministic entity / world-model engine for AI agents.** (The brand is
4
+ **Cairn**; the distribution is `cairn-engine` and the import package is
5
+ `cairn_engine`.)
6
+
7
+ Resolve messy human references to stable canonical IDs, traverse their relations
8
+ bi-temporally, and author the frozen alias table that makes it all reproducible —
9
+ storage-agnostic, local-first, **zero generative-LLM and zero network on the
10
+ default path**, **zero runtime dependencies** (pure stdlib).
11
+
12
+ `cairn-engine` is the foundational entity subsystem. The agent-retrieval layer
13
+ (gate, signals, fusion, assembler) lives in the separate
14
+ [`cairn-retrieval`](https://github.com/leocelis/cairn/tree/main/packages/cairn-retrieval)
15
+ package, which depends on this one.
16
+
17
+ > **Status:** feature-complete, pre-release (0.1.0) — full resolution cascade,
18
+ > bounded bi-temporal traversal, ontology authoring + 3-tier dedup, SQLite and
19
+ > openCypher adapters, and a cross-system entity index. 120 tests, ruff + mypy
20
+ > strict, byte-stable. The retrieval-quality benchmark (OP-31) is the next phase;
21
+ > until then, treat determinism/portability as proven and quality as unclaimed.
22
+ > See the [roadmap](https://github.com/leocelis/cairn/blob/main/ROADMAP.md).
23
+
24
+ ## Install
25
+
26
+ ```bash
27
+ pip install cairn-engine
28
+ ```
29
+
30
+ ## Quickstart
31
+
32
+ ```python
33
+ from cairn_engine import (
34
+ Entity, InMemoryAliasTable, InMemoryGraph, Ref, Relation, resolve, traverse,
35
+ )
36
+
37
+ entities = [
38
+ Entity("account::schwab_main", "Schwab", "config", aliases=("my Schwab account",),
39
+ refs=(Ref(doc_id="doc::accounts"),)),
40
+ Entity("doc::payment_retry_policy", "Payment Retry Policy", "document",
41
+ refs=(Ref(doc_id="doc::retry"),),
42
+ relations=(Relation("references", "account::schwab_main"),)),
43
+ ]
44
+
45
+ table = InMemoryAliasTable.from_entities(entities) # build -> freeze -> read-only
46
+ graph = InMemoryGraph.from_entities(table.canonical_entities())
47
+
48
+ resolved, unresolved = resolve("does the payment retry policy touch my Schwab account?",
49
+ table=table)
50
+ # both entities found by gazetteer scan; unresolved == [] (a miss is never a made-up ID)
51
+
52
+ result = traverse(resolved[0].canonical_id, graph=graph, depth=2)
53
+ # connected DocumentRefs, hop-scored 1/(1+hop), byte-stable
54
+ ```
55
+
56
+ The resolution cascade: **exact → normalized (NFKC) → fuzzy (token-sort ≥ 0.85,
57
+ entropy-gated) → semantic (opt-in: your embedder) → LLM arbiter (opt-in: your
58
+ callable; picks among presented candidates in the 0.70–0.85 band — never mints an
59
+ ID)**. Misses come back in `unresolved` — never a synthesized ID (closed world).
60
+
61
+ Build-time authoring (offline, human-gated): `author_from_text` →
62
+ `dedup_candidates` (exact → MinHash/LSH → review band, never auto-merged) → your
63
+ approval → `freeze()`. Optional extractors (GLiNER / LLM) enter as callables you
64
+ supply — the engine never imports third-party packages or calls APIs.
65
+
66
+ Also here: bi-temporal state (`as_at`, `supersede`), a cross-system entity index
67
+ (`CrossSystemIndex`), a SQLite alias-table backend, and an openCypher compiler
68
+ (`compile_traversal` / `traverse_cypher`) that runs the same bounded traversal on
69
+ Neo4j / FalkorDB — the engine imports no DB driver; you pass the connection.
70
+
71
+ ## Design foundations
72
+
73
+ Grounded in five CS theories (canonicalization over equivalence classes, labeled
74
+ property graphs, the bi-temporal model, bounded transitive closure, and the
75
+ closed-world assumption) — see
76
+ [`docs/patterns/`](https://github.com/leocelis/cairn/tree/main/docs/patterns) and
77
+ [`docs/research/foundations/`](https://github.com/leocelis/cairn/tree/main/docs/research/foundations).
78
+ Every module is developed intent-first ([IVD](https://ivdframework.dev)):
79
+ constraints in `intents/` map 1:1 to tests with hand-computed golden fixtures.
80
+
81
+ ## License
82
+
83
+ MIT — Copyright (c) 2026 Leo Celis
@@ -0,0 +1,129 @@
1
+ # ==============================================================================
2
+ # Cairn — Module Intent: cross-system entity index (M2.4)
3
+ # ==============================================================================
4
+ # License: MIT · Copyright (c) 2026 Leo Celis · https://ivdframework.dev
5
+ # Parent: ../../../cairn_system_intent.yaml (v0.2.1)
6
+ # Patterns: patterns_entities.yaml — OP-28 (canonicalization), TH-1 (equivalence
7
+ # classes), TH-5 (closed world). Research finding: cross_system_entity_index.
8
+ # ==============================================================================
9
+
10
+ scope:
11
+ level: "module"
12
+ type: "feature"
13
+ granularity: "fine"
14
+
15
+ metadata:
16
+ feature_id: "cairn_cross_system_index"
17
+ category: "agent_infrastructure"
18
+ tags: ["cross-system", "identity", "tool-arg-binding", "closed-world", "deterministic"]
19
+ status: "in_progress"
20
+ introduced_version: "0.2.0"
21
+
22
+ intent:
23
+ summary: >
24
+ A unified index mapping ONE canonical entity to its many system-specific IDs
25
+ ({crm: "cus_42", slack: "C0299", github: "acme-inc"}), bidirectionally and
26
+ deterministically. Lets an agent resolve a mention to a canonical entity and
27
+ then bind the RIGHT external ID when it calls a tool against a given system.
28
+ goal: |
29
+ Failure this fixes (research finding cross_system_entity_index): tool systems
30
+ become cold silos — the right tool is selected but the arg binds to the WRONG
31
+ namespace ID (system-A id vs system-B id vs symbol for the same "Acme"). The
32
+ index makes canonical->system-id binding a lookup, not a guess.
33
+
34
+ Deliverables (a build->freeze->read-only index, like the alias table):
35
+ 1. external_ids(canonical_id, *, system) -> tuple[str, ...] (all ids the
36
+ entity has in that system; sorted; empty tuple on miss — never guessed)
37
+ 2. bind(canonical_id, *, system) -> str | None (the single id for a
38
+ tool-arg; None if the entity has none in that system; ValueError if the
39
+ entity has MORE than one there — an ambiguity the caller must resolve)
40
+ 3. canonical_for(system, external_id) -> str | None (reverse: which
41
+ canonical owns this system id; None on miss — closed world)
42
+ 4. systems(canonical_id) -> tuple[str, ...] (which systems this entity is
43
+ known in)
44
+ Build from explicit (canonical_id, system, external_id) entries or from
45
+ Entity.metadata["system_ids"] (a documented convention: {system: id | [ids]}).
46
+ success_metric: "All constraint tests pass under the project venv (python 3.11), stdlib-only, byte-stable; closed-world (no synthesized id) on every miss."
47
+ stakeholders:
48
+ - "agents doing multi-system tool calls (bind canonical -> correct system id at arg time)"
49
+ - "OQ-1 (unified entity index — partial)"
50
+
51
+ design_decisions:
52
+ reverse_key_is_system_scoped:
53
+ decision: "The reverse index is keyed by (system, external_id), not external_id alone."
54
+ rationale: "The same external_id STRING can legitimately exist in two systems ('123' in CRM and in GitHub). Scoping by system keeps the reverse map unambiguous."
55
+ reverse_is_one_to_one:
56
+ decision: "Within a system, an external_id maps to AT MOST one canonical entity. A second canonical claiming the same (system, external_id) is a data error and raises at freeze."
57
+ rationale: "TH-1: canonicalization is an equivalence-class partition; a system id belonging to two canonicals means the two are actually the same entity (should be merged) — silently picking one corrupts binding."
58
+ forward_is_one_to_many:
59
+ decision: "One canonical MAY have multiple ids in the same system (e.g. after a TH-1 merge of two records that each had a system id). external_ids returns all (sorted); bind requires exactly one."
60
+ rationale: "Merges are real; losing a merged-away system id would break reverse lookups for that id. bind() surfaces the ambiguity instead of hiding it."
61
+
62
+ interface:
63
+ type: "library"
64
+ tools:
65
+ - name: "CrossSystemIndex"
66
+ description: "Build (add / from_entries / from_entities) -> freeze() -> read-only bidirectional lookup. Frozen == deterministic boundary (like the alias table)."
67
+ returns: "CrossSystemIndex"
68
+ test: "packages/cairn-engine/tests/unit/test_cross_system.py"
69
+
70
+ constraints:
71
+ - id: "C-XSYS-1"
72
+ statement: "Forward: external_ids(cid, system=s) returns exactly the ids entity cid has in system s, sorted, as a tuple; systems(cid) returns cid's systems sorted. Both return () on an unknown cid or unknown system (no error, no guess)."
73
+ assumption_status: "KNOWN"
74
+ test: "packages/cairn-engine/tests/unit/test_cross_system.py::test_forward_lookup"
75
+ test_provenance: "human_authored"
76
+
77
+ - id: "C-XSYS-2"
78
+ statement: "Reverse: canonical_for(system=s, external_id=x) returns the canonical id that owns (s, x). The reverse key is (system, external_id) — the same external_id string in a different system does NOT collide."
79
+ assumption_status: "KNOWN"
80
+ test: "packages/cairn-engine/tests/unit/test_cross_system.py::test_reverse_lookup_system_scoped"
81
+ test_provenance: "human_authored"
82
+
83
+ - id: "C-XSYS-3"
84
+ statement: "bind(cid, system=s): returns the single external id when cid has exactly one in s; returns None when cid has none in s; raises ValueError (ambiguous) when cid has 2+ in s. Built from Entity.metadata['system_ids'] accepting both a scalar id and a list of ids."
85
+ assumption_status: "KNOWN"
86
+ test: "packages/cairn-engine/tests/unit/test_cross_system.py::test_bind_cardinality"
87
+ test_provenance: "human_authored"
88
+
89
+ - id: "C-XSYS-4"
90
+ statement: "Reverse one-to-one integrity: two DISTINCT canonical ids mapped to the same (system, external_id) raise ValueError at freeze. The same (cid, system, external_id) added twice is idempotent (no error)."
91
+ assumption_status: "KNOWN"
92
+ test: "packages/cairn-engine/tests/unit/test_cross_system.py::test_reverse_collision_raises"
93
+ test_provenance: "human_authored"
94
+
95
+ # CRITICAL, LAST — the closed-world keystone (TH-5) + determinism.
96
+ - id: "C-XSYS-5"
97
+ statement: "CLOSED WORLD: every miss (unknown canonical, unknown system, unknown external id) returns () or None — NEVER a synthesized/guessed id. The index is byte-stable (deterministic order, no wall clock), read-only after freeze (mutation raises), and imports nothing outside stdlib."
98
+ assumption_status: "KNOWN"
99
+ conflict_prone: true
100
+ anti_pattern: "On a miss, fabricating a plausible external id (e.g. slugifying the label into 'acme-inc') so the tool call 'has something'. That is the exact hallucinated-binding failure cairn exists to remove — a miss must be an explicit None."
101
+ test: "packages/cairn-engine/tests/unit/test_cross_system.py::test_closed_world_and_byte_stable"
102
+ test_provenance: "execution_derived"
103
+ execution_oracle:
104
+ type: "differential_test"
105
+ note: "Assert None/() on unknown inputs; freeze twice from the same entries and assert identical serialized state; static-check the module imports only stdlib."
106
+
107
+ constraint_satisfiability:
108
+ count: 5
109
+ joint_satisfaction_test: "packages/cairn-engine/tests/unit/test_cross_system.py::test_joint_cross_system"
110
+ joint_note: >
111
+ One test: build from entities carrying system_ids incl. a TH-1 merge (one
112
+ canonical with two ids in one system), freeze, then forward (C-1), reverse
113
+ system-scoped (C-2), bind cardinality incl. the ambiguous case (C-3), and a
114
+ miss returning None (C-5) — all on the same frozen index, byte-stable.
115
+ conflicts_checked: >
116
+ C-3 (forward one-to-many) vs C-4 (reverse one-to-one): consistent — one
117
+ canonical may own several system ids (forward), but each system id is owned
118
+ by one canonical (reverse). C-5 (closed world) vs all: reinforces — misses
119
+ are None, never fabricated.
120
+
121
+ non_goals:
122
+ - "Fetching from the external systems (this is an ID map, not a connector; the caller's tools do I/O)."
123
+ - "Fuzzy / semantic matching of external ids (exact identity only — resolution lives in resolve())."
124
+ - "Auto-detecting system_ids from arbitrary metadata shapes (only the documented system_ids convention)."
125
+
126
+ changelog:
127
+ - version: "0.1.0"
128
+ date: "2026-07-12"
129
+ change: "Initial intent for M2.4 cross-system entity index. Bidirectional canonical<->{system ids}, closed-world (no synthesis), reverse one-to-one integrity at freeze, forward one-to-many for TH-1 merges, bind() with explicit ambiguity. 5 constraints, closed-world keystone (conflict_prone) last; joint test defined."
@@ -0,0 +1,186 @@
1
+ # ==============================================================================
2
+ # Cairn — Module Intent: bi-temporal state (M2.1)
3
+ # ==============================================================================
4
+ # License: MIT · Copyright (c) 2026 Leo Celis · https://ivdframework.dev
5
+ # Parent: ../../../cairn_system_intent.yaml (v0.2.1)
6
+ # Patterns: patterns_entities.yaml — TH-3 (Bitemporal State Model), OP-28
7
+ # (bi_temporal_model), OP-34 (traversal temporal filter), OP-35
8
+ # (four-column schema), TH-5 (CWA)
9
+ # Resolves: OQ-4 (open-end interval sentinel — NULL vs +infinity)
10
+ # ==============================================================================
11
+
12
+ scope:
13
+ level: "module"
14
+ type: "feature"
15
+ granularity: "fine"
16
+
17
+ metadata:
18
+ feature_id: "cairn_entity_bitemporal"
19
+ category: "agent_infrastructure"
20
+ tags: ["bitemporal", "valid-time", "transaction-time", "point-in-time", "audit", "deterministic"]
21
+ status: "in_progress"
22
+ introduced_version: "0.2.0"
23
+
24
+ intent:
25
+ summary: >
26
+ Complete the bi-temporal model (TH-3): the valid-time axis
27
+ (valid_from/valid_until) already exists on Entity and Relation; add the
28
+ SECOND axis, transaction-time (known_from/known_until = when the system
29
+ learned the fact), plus a point-in-time query (as_at) over both axes and an
30
+ append-only supersession helper — all deterministic, wall-clock-free,
31
+ stdlib-only.
32
+ goal: |
33
+ Today a fact carries one time axis (valid-time): "when was this TRUE in the
34
+ world." That answers correctness but not audit — "what did the agent KNOW,
35
+ and when." A single axis conflates the two (TH-3). M2.1 adds transaction-time
36
+ so both questions are answerable and every correction is preserved, never
37
+ overwritten (append-only history = auditability, the trust wedge).
38
+
39
+ Deliverables:
40
+ 1. known_from / known_until on Entity AND Relation (transaction-time axis),
41
+ default None, round-tripping in JSON.
42
+ 2. as_at(...) — a pure point-in-time filter over the four columns.
43
+ 3. supersede(...) — record a new version of a fact without deleting the
44
+ old one (append-only): the old version's known_until is closed, the new
45
+ version's known_from opens; the old record itself is never mutated.
46
+ 4. traverse(...) gains an optional known_as_of so edges can be filtered on
47
+ BOTH axes (valid AND transaction), not just valid-time.
48
+
49
+ The CORE owns these pure functions; they operate OVER value records (TH-5),
50
+ never as methods on them. Transaction-time is a caller-supplied EXPLICIT
51
+ input — cairn never stamps now() (that would break byte-stability and the
52
+ determinism invariant; see C-BITEMP-5).
53
+ success_metric: "All constraint tests pass under the project venv (python 3.11), stdlib-only, byte-stable across runs; joint_satisfaction_test green."
54
+ stakeholders:
55
+ - "cairn users (agents that must answer 'what did I know at T' and correct facts without losing history)"
56
+ - "traverse() (bitemporal edge filter, both axes)"
57
+ - "cairn-retrieval (point-in-time context assembly)"
58
+
59
+ # ------------------------------------------------------------------------------
60
+ # Design decisions pinned by this intent (OQ-4 + naming + wall-clock)
61
+ # ------------------------------------------------------------------------------
62
+ design_decisions:
63
+ open_end_sentinel: # resolves OQ-4
64
+ decision: "None is the open end (== +infinity). Intervals are half-open [start, end)."
65
+ predicate: "in-interval(T) := (start is None or start <= T) and (end is None or T < end)"
66
+ rationale: >
67
+ Pins the ambiguous 'T < end' comparison from TH-3's design_consequence.
68
+ None already means 'open' in the existing _edge_valid; making it the ONE
69
+ sentinel across both axes keeps a single comparison rule. A sentinel
70
+ string (+infinity) would sort lexicographically against real ISO dates and
71
+ is a foot-gun; None is unambiguous and type-clean.
72
+ axis_naming:
73
+ decision: "Transaction-time fields are known_from / known_until (symmetric with the existing valid_from / valid_until valid-time pair)."
74
+ maps_to: "Snodgrass/SQL:2011 transaction-time [created_at, expired_at]; Graphiti t_created/t_expired. known_* is the plain-English form of the audit question 'what did the agent KNOW at T'."
75
+ transaction_time_is_explicit:
76
+ decision: "known_from / known_until are caller-supplied. Cairn NEVER derives them from the wall clock."
77
+ rationale: "The whole thesis is a deterministic, byte-stable world model. now() at ingestion would make two builds of the same corpus differ. The caller passes its ingestion instant (batch timestamp / monotonic version), exactly as `as_of` is explicit in traverse."
78
+
79
+ interface:
80
+ type: "library"
81
+ tools:
82
+ - name: "as_at"
83
+ description: "as_at(facts, *, valid_as_of=None, known_as_of=None) -> tuple[...]. Returns the subset of facts (Entities or Relations) whose valid-time interval contains valid_as_of AND whose transaction-time interval contains known_as_of. None on an axis = do not filter that axis. Half-open, None = open end."
84
+ parameters:
85
+ - name: "facts"
86
+ type: "iterable"
87
+ required: true
88
+ description: "Entities or Relations (anything carrying the four time columns)"
89
+ - name: "valid_as_of"
90
+ type: "string"
91
+ required: false
92
+ description: "ISO 8601 instant on the valid-time axis; None = do not filter valid-time"
93
+ - name: "known_as_of"
94
+ type: "string"
95
+ required: false
96
+ description: "ISO 8601 instant on the transaction-time axis; None = do not filter transaction-time"
97
+ returns: "tuple of the input facts that pass the four-column predicate, order preserved"
98
+ test: "packages/cairn-engine/tests/unit/test_bitemporal.py::test_as_at_four_column"
99
+ - name: "supersede"
100
+ description: "supersede(history, new_fact, *, at) -> tuple[...]. Append-only correction: closes the known_until of the currently-known matching fact(s) at `at`, sets new_fact.known_from = at, and returns the FULL history (old versions retained + new version appended). Never mutates or drops a record."
101
+ parameters:
102
+ - name: "history"
103
+ type: "iterable"
104
+ required: true
105
+ description: "The existing versions (Entities or Relations sharing identity)"
106
+ - name: "new_fact"
107
+ type: "object"
108
+ required: true
109
+ description: "The new version to record"
110
+ - name: "at"
111
+ type: "string"
112
+ required: true
113
+ description: "ISO 8601 transaction-time instant of the correction (explicit — never now())"
114
+ returns: "tuple: prior versions (with known_until closed on the superseded one) + the new version"
115
+ test: "packages/cairn-engine/tests/unit/test_bitemporal.py::test_supersede_append_only"
116
+
117
+ # ------------------------------------------------------------------------------
118
+ # Constraints — critical LAST (position bias; UltraBench 2025).
119
+ # Each maps 1:1 to a named test. 5 constraints -> joint_satisfaction required.
120
+ # ------------------------------------------------------------------------------
121
+ constraints:
122
+ - id: "C-BITEMP-1"
123
+ statement: "Entity and Relation each carry transaction-time columns known_from / known_until (default None), independent of the existing valid_from / valid_until valid-time columns. Both axes round-trip byte-identically through dump_entities/load_entities."
124
+ assumption_status: "KNOWN"
125
+ test: "packages/cairn-engine/tests/unit/test_bitemporal.py::test_four_columns_roundtrip"
126
+ test_provenance: "human_authored"
127
+
128
+ - id: "C-BITEMP-2"
129
+ statement: "as_at filters on BOTH axes with the four-column half-open predicate. 'What was TRUE at T': valid_from <= T < valid_until. 'What was KNOWN at T': known_from <= T < known_until. A None argument on an axis disables filtering on that axis only."
130
+ assumption_status: "KNOWN"
131
+ test: "packages/cairn-engine/tests/unit/test_bitemporal.py::test_as_at_four_column"
132
+ test_provenance: "human_authored"
133
+ execution_oracle:
134
+ type: "golden_fixture"
135
+ note: "Hand-computed: a fact valid last Tuesday but known only from today is excluded by known_as_of=Tuesday, included by known_as_of=today; valid_as_of=Tuesday includes it on the valid axis. All four boundary cases asserted."
136
+
137
+ - id: "C-BITEMP-3"
138
+ statement: "The open-end sentinel is None == +infinity (OQ-4). At the boundary, an interval [start, None) contains every T >= start; [start, end) EXCLUDES T == end (half-open). Applied identically to valid-time and transaction-time."
139
+ assumption_status: "KNOWN"
140
+ test: "packages/cairn-engine/tests/unit/test_bitemporal.py::test_open_end_sentinel_boundary"
141
+ test_provenance: "human_authored"
142
+
143
+ - id: "C-BITEMP-4"
144
+ statement: "Supersession is append-only and immutable: after supersede(history, new, at), the prior record objects are NOT mutated (frozen), NO record is dropped, the superseded version's known_until == at, and the new version's known_from == at. The full audit chain (what was known, when) is reconstructable via as_at over the returned history."
145
+ assumption_status: "KNOWN"
146
+ test: "packages/cairn-engine/tests/unit/test_bitemporal.py::test_supersede_append_only"
147
+ test_provenance: "human_authored"
148
+
149
+ # CRITICAL, LAST — contradicts the domain prior (every bitemporal DB stamps
150
+ # transaction-time with now() automatically). conflict_prone.
151
+ - id: "C-BITEMP-5"
152
+ statement: "NO WALL CLOCK. Neither as_at, supersede, nor the model reads the system clock (no datetime.now / time.time / date.today). Transaction-time is always a caller-supplied explicit instant. Two runs over the same inputs produce byte-identical output."
153
+ assumption_status: "KNOWN"
154
+ conflict_prone: true
155
+ anti_pattern: "Auto-stamping known_from = datetime.now(timezone.utc) at ingestion 'like a real temporal DB'. This is the trained-in default and it silently breaks byte-stability + determinism (cairn_system_intent invariant deterministic_resolution_no_llm)."
156
+ test: "packages/cairn-engine/tests/unit/test_bitemporal.py::test_no_wall_clock_byte_stable"
157
+ test_provenance: "execution_derived"
158
+ execution_oracle:
159
+ type: "differential_test"
160
+ note: "Build + as_at + supersede twice in one process and assert byte-identical repr/JSON; grep the module source for now()/today()/time( as a static guard."
161
+
162
+ constraint_satisfiability:
163
+ count: 5
164
+ joint_satisfaction_test: "packages/cairn-engine/tests/unit/test_bitemporal.py::test_joint_bitemporal"
165
+ joint_note: >
166
+ One test that: builds a small history with both axes set, runs a correction
167
+ via supersede (C-4), queries it with as_at at three (valid, known) points
168
+ (C-2) exercising the None open-end (C-3) on four columns that round-tripped
169
+ through JSON (C-1), and asserts the whole thing is byte-stable with no clock
170
+ read (C-5). Individual passes do not imply this joint pass.
171
+ conflicts_checked: >
172
+ C-5 (no wall clock) vs C-4 (supersede sets known_until=at): no conflict —
173
+ `at` is the caller's explicit instant, not now(). C-3 (None open end) vs C-2
174
+ (half-open predicate): consistent — None short-circuits the comparison. No
175
+ two constraints require mutating a frozen record (C-4 forbids it).
176
+
177
+ non_goals:
178
+ - "Automatic ingestion timestamping (explicit-only; see C-BITEMP-5)."
179
+ - "Allen's full 13 interval relations as an API — only the point-in-time (as_at) and meets-style supersession are in scope for M2.1; interval-algebra queries are a later opt-in."
180
+ - "Temporal indexing / range trees — M2.1 is linear-scan pure functions; a temporal index is a backend-adapter concern (storage_agnostic_core)."
181
+ - "Renaming the existing valid_from/valid_until (no breaking change)."
182
+
183
+ changelog:
184
+ - version: "0.1.0"
185
+ date: "2026-07-12"
186
+ change: "Initial intent for M2.1 bi-temporal state. Resolves OQ-4 (None = open-end sentinel). Adds transaction-time (known_from/known_until), as_at point-in-time query, append-only supersede, and a both-axes traverse filter. 5 constraints, critical (no-wall-clock, conflict_prone) last; joint_satisfaction_test defined."