Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -154,5 +154,5 @@ and flow downward.
| [plan/analysis/p3_agent_navigation.md](plan/analysis/p3_agent_navigation.md) | P3 agent navigation — materialized tree vs index-only, the `_index.md` contract, facets/views/fan-out, why directory LLM summaries are rejected (→ e0 §6, F6) |
| [plan/plans/roadmap.md](plan/plans/roadmap.md) | Build order: phase spine, stack, gate register, WP format (phases 0–8) |
| [plan/designs/packaging_distribution_design.md](plan/designs/packaging_distribution_design.md) | Delivery artifacts, delivery-only task execution, enforced code architecture (D62) |
| [decisions.md](decisions.md) | Architecture decision log (D1–D63) with rationale |
| [decisions.md](decisions.md) | Architecture decision log (D1–D64) with rationale |
| [questions.md](questions.md) | Open questions to resolve before building |
38 changes: 38 additions & 0 deletions decisions.md
Original file line number Diff line number Diff line change
Expand Up @@ -424,6 +424,10 @@ supersession (`registries_design.md` §4, extension packs).
representation of time. A claim's immutable asserted-validity interval (D41) is *claim metadata*, not
a relation object/predicate or a Date-node, so it is fully compatible — D18 is unchanged.

**Refined by D64.** The seed core is now 8 types + **16** predicates: `uses`
(Person | Organization → Product) and `reports_to` (Person → Person) promoted from the
registries §4 watchlist — the first watchlist graduations. Everything else here is unchanged.

## D19. Coref is satisfied inside the E2 extraction call (no dedicated model)

**Decision.** Coref is the guarantee that no claim leaves E2 with a dangling pronoun — satisfied
Expand Down Expand Up @@ -1768,3 +1772,37 @@ three-calls-per-chunk math). E1 spike 8 narrows from "which model" to "which sto
prefix quality", measured on the golden set. P1 index/parameter choices unblock (dimension now
bounded). Questions #3 closes; review finding F8 closes. The embedder port gains its two named
adapters (OpenRouter-hosted; self-hosted weights).

## D64. Core predicates grow to 16 — `uses` and `reports_to` promoted from the watchlist

**Decision.** The D18 seed core gains two predicates, taking the core from 14 to **16**:
**`uses`** (Person | Organization → Product — adoption/consumption of a product/system/tool;
change-prone, ordinary supersession; deliberately distinct from `works_on`, which means
building/active engagement, not using) and **`reports_to`** (Person → Person — the
organizational reporting line; change-prone). Both move from the predicate watchlist
(registries §4) into the core table with these tight signatures; their formerly designated
pack homes (systems; work/HR) no longer apply to them. The watchlist keeps `owns`/
`acquired_by`, `lives_in`, and the guardrailed `enables`; the D5 `other:` promotion funnel
remains the default path for everything else — this is an owner promotion, not a change to
the funnel rule.

**Context.** The watchlist promotes on demonstrated `other:` volume, not intuition. These two
are promoted ahead of volume because every named deployment (registries §1) needs them
first-class from day one: "who uses which system/tool" is the backbone of the migration
deployment's as-is landscape and a bread-and-butter assistant/agency query ("person A uses
software X"), and `reports_to` is the org-chart backbone of people-centric retrieval. Both
carry exactly the properties that qualified the original fourteen: tight domain/range over
core types (the D18 gate bites), natural evidence aggregation (the same usage/reporting fact
recurs across sources), and clean supersession semantics (tool adoption and reporting lines
end and change — the bi-temporal model fits). Waiting for the funnel would have meant an
interim of `other:uses` / `other:reports_to` edges that bypass domain/range validation
(tier='other' is ungoverned until promotion) for facts already known to be wanted governed.

**Consequences.** Registries §4: the core table has 16 rows (`related_to` stays last as the
permissive parent); the watchlist shrinks to three entries. p2 §3's seed vocabulary updated;
extraction prompts pick both up by registry render (D15 — rows, not prompt engineering).
Core-tier obligations attach: D22 golden-set coverage for both, and the core stability
commitment (a future split pays the D15-flagged split cost). Signature notes: systems-pack
subtypes (`System`/`Module ⊂ Product`) inherit into `uses`'s range via D15 inheritance;
`reports_to` stays strictly person-to-person (a role-based reporting line is modeled through
the person holding the role).
3 changes: 2 additions & 1 deletion plan/designs/k_layers_design.md
Original file line number Diff line number Diff line change
Expand Up @@ -699,7 +699,8 @@ between compiled and authored does **not** fall on the as-is/to-be line. The lin
any other; only content no source yet attests must be authored.

- The systems extension pack (registries §4) makes the landscape *entities*:
`System`/`Module ⊂ Product`, `BusinessProcess ⊂ Concept`, predicates `uses`, `depends_on`,
`System`/`Module ⊂ Product`, `BusinessProcess ⊂ Concept`, predicates `uses` (core since D64,
inherited by the pack's subtypes), `depends_on`,
`part_of`. Workshop notes, emails, and specs from different people all resolve onto the same
module entities — that is plane E doing its job.
- **`as-is/` is compiled.** The ordering-subsystem page holds an `entity_subtree` rule on the
Expand Down
2 changes: 1 addition & 1 deletion plan/designs/overall_design.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

The architecture that satisfies `plan/requirements/requirements_v3.md`. This document is the
map; per-layer designs (this directory) are the territory. Decision rationale lives in
`decisions.md` (root, cited as D1–D63); supporting research in `plan/analysis/`.
`decisions.md` (root, cited as D1–D64); supporting research in `plan/analysis/`.

## 1. System overview: three planes (D14)

Expand Down
7 changes: 4 additions & 3 deletions plan/designs/p2_graph_design.md
Original file line number Diff line number Diff line change
Expand Up @@ -136,9 +136,10 @@ both entity-keyed blocking and graph queries. So:
hatch.
- A periodic job reviews frequent `other:` values and promotes them (or maps them to existing
predicates). The ontology evolves by governance, not by accretion.
- Seed vocabulary = the **14 D18 core predicates** (`works_for, member_of, affiliated_with, founded,
located_in, part_of, authored, created, about, knows_about, knows, participated_in, works_on,
related_to`); the authoritative list + domain/range signatures live in `registries_design.md` §4.
- Seed vocabulary = the **16 core predicates** (D18, extended by D64: `works_for, member_of,
affiliated_with, founded, located_in, part_of, authored, created, about, knows_about, knows,
participated_in, works_on, uses, reports_to, related_to`); the authoritative list +
domain/range signatures live in `registries_design.md` §4.
Extend per K2 domain via packs. (The graph stores `predicate` as a property — D18 domain/range is
enforced upstream by the E3 normalizer, not in the graph.)

Expand Down
4 changes: 2 additions & 2 deletions plan/designs/postgres_schema_design.md
Original file line number Diff line number Diff line change
Expand Up @@ -494,8 +494,8 @@ COMMENT ON TABLE scope_interests IS
'Per-scope interest list (D16): the predicate/type footprint that defines the scope''s PROJECT_GRAPH_CYPHER view and what its K2 compilation selects. A query/compile-time selection over fully-extracted facts — never a promotion trigger (D28 withdrawn).';
```

The **seed core** (D18) — 8 entity types and 14 predicates with signatures — is data inserted by a
migration, not schema. Its authoritative list is in `registries_design.md` §4; the seeding
The **seed core** (D18, extended by D64) — 8 entity types and 16 predicates with signatures — is
data inserted by a migration, not schema. Its authoritative list is in `registries_design.md` §4; the seeding
migration cites that section rather than duplicating it here (avoids drift).

---
Expand Down
19 changes: 12 additions & 7 deletions plan/designs/registries_design.md
Original file line number Diff line number Diff line change
Expand Up @@ -130,10 +130,10 @@ One canonical cascade. Stop at the first confident match. **Registry-self-contai

## 4. Ontology — universal core + anchored extensions (D15, D18)

- **Seed core (D18):** 8 entity types — `Person, Organization, Place, Document⊂CreativeWork,
Event, Concept, Project, Product` — and the 14 core predicates below. `related_to` is the
predicate-side core parent (the extend-never-fork anchor + permissive escape). Time is
bi-temporal edge metadata, never a predicate/Date-node.
- **Seed core (D18, extended by D64):** 8 entity types — `Person, Organization, Place,
Document⊂CreativeWork, Event, Concept, Project, Product` — and the 16 core predicates below.
`related_to` is the predicate-side core parent (the extend-never-fork anchor + permissive
escape). Time is bi-temporal edge metadata, never a predicate/Date-node.

**Core predicates (the authoritative starting set — domain/range is the enforced signature):**

Expand All @@ -152,7 +152,9 @@ One canonical cascade. Stop at the first confident match. **Registry-self-contai
| 11 | `knows` | Person → Person | social graph |
| 12 | `participated_in` | Person \| Organization → Event \| Project | involvement |
| 13 | `works_on` | Person \| Organization → Project \| Product | active engagement — change-prone |
| 14 | `related_to` | any → any | permissive core parent (escape + extend-never-fork anchor) |
| 14 | `uses` | Person \| Organization → Product | adoption/consumption of a product/system/tool — change-prone; distinct from `works_on` (building ≠ using) — promoted from the watchlist, D64 |
| 15 | `reports_to` | Person → Person | organizational reporting line — change-prone (supersession) — promoted from the watchlist, D64 |
| 16 | `related_to` | any → any | permissive core parent (escape + extend-never-fork anchor) |

Multi-signature predicates list each allowed `(subject_type, object_type)` pair (Graphiti
`edge_type_map` shape); subtypes inherit a parent's signatures (D15). Schema.org property
Expand Down Expand Up @@ -246,10 +248,13 @@ into the appropriate pack with a tight signature. Adding one is a registry row;
premature core predicate (prompt space, golden-set coverage, a split if it's wrong) is the
reason to wait.

**Two graduations (D64):** `uses` and `reports_to` were promoted into the core (rows 14–15
above) by owner decision — the named deployments made the demand case without waiting for
`other:` volume (an as-is system landscape runs on `uses`; people-centric retrieval runs on
`reports_to`). The rows below remain held back.

| Candidate | Tight signature | Future home |
|---|---|---|
| `uses` | Organization \| Person → Product | systems pack |
| `reports_to` | Person → Person | work/HR pack |
| `owns` / `acquired_by` | Organization → Organization \| Product | business pack |
| `lives_in` | Person → Place | personal pack |
| `enables` | Concept → Concept (tight only) | research scope — guardrailed (see below) |
Expand Down
6 changes: 3 additions & 3 deletions questions.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ The living register of **what is not settled yet** — open decisions, unwritten
designs, known risks, and concrete inconsistencies to fix. It is the one place to look for "what's
still open"; it cross-links the two specialized trackers:

- **`decisions.md`** — what *is* decided (D1–D63).
- **`decisions.md`** — what *is* decided (D1–D64).
- **`plan/analysis/objections.md`** — the step-back critique (O1–O6) with accept/reject status.
- The **design-doc index** in `plan/designs/overall_design.md` — which design docs are written
(`current`) vs. `planned`.
Expand Down Expand Up @@ -161,7 +161,7 @@ Keep this current: when something here is decided, move it to a decision and pru
still says** "row counts are contingent on the value gate — size against *gated* volume." Update
D23.
27. ~~**P2 graph design ontology is stale vs D18.**~~ **RESOLVED (D44).** `p2_graph_design.md` §2/§3 now
use the D18 seed core (8 types + 14 predicates), `DOC_CROSSREF(kind)` (generalizing the old `CITES`),
use the D18/D64 seed core (8 types + 16 predicates), `DOC_CROSSREF(kind)` (generalizing the old `CITES`),
and the `IS_DOCUMENT` bridge — see the Postgres→LadybugDB translation analysis
(`plan/analysis/ladybug_translation_research/SYNTHESIS.md`) and the `v_graph_*` projection views
(`postgres_schema_design.md` §10.A).
Expand Down Expand Up @@ -191,7 +191,7 @@ Keep this current: when something here is decided, move it to a decision and pru
belief tier. Open remainders stay tracked above (#5 whose-beliefs, #6 cadence, #24 hard-delete
residuals) and in the design's §11 spikes.

- **Ontology seed** (was "what seeds the ontology") → **D18** (8 core types + 14 predicates with
- **Ontology seed** (was "what seeds the ontology") → **D18** (8 core types + 14 predicates, since grown to 16 by D64, with
domain/range; extension packs; `other:` promotion).
- **Multi-tenant / ID scoping** (was "single user or multi-tenant") → **D16** + the deployment model
(`registries_design.md` §1): separate deployments = separate Postgres instances + entity spaces.
Expand Down
Loading