diff --git a/README.md b/README.md index ed3a5e2..9c8a21d 100644 --- a/README.md +++ b/README.md @@ -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 | diff --git a/decisions.md b/decisions.md index c7d23d0..e344aad 100644 --- a/decisions.md +++ b/decisions.md @@ -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 @@ -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). diff --git a/plan/designs/k_layers_design.md b/plan/designs/k_layers_design.md index e977641..ab6214b 100644 --- a/plan/designs/k_layers_design.md +++ b/plan/designs/k_layers_design.md @@ -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 diff --git a/plan/designs/overall_design.md b/plan/designs/overall_design.md index c013964..7e05ce9 100644 --- a/plan/designs/overall_design.md +++ b/plan/designs/overall_design.md @@ -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) diff --git a/plan/designs/p2_graph_design.md b/plan/designs/p2_graph_design.md index 79f77c1..09c5951 100644 --- a/plan/designs/p2_graph_design.md +++ b/plan/designs/p2_graph_design.md @@ -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.) diff --git a/plan/designs/postgres_schema_design.md b/plan/designs/postgres_schema_design.md index 85c3827..c43568d 100644 --- a/plan/designs/postgres_schema_design.md +++ b/plan/designs/postgres_schema_design.md @@ -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). --- diff --git a/plan/designs/registries_design.md b/plan/designs/registries_design.md index 270fd4c..b10f291 100644 --- a/plan/designs/registries_design.md +++ b/plan/designs/registries_design.md @@ -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):** @@ -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 @@ -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) | diff --git a/questions.md b/questions.md index 8945a94..f7dfa46 100644 --- a/questions.md +++ b/questions.md @@ -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`. @@ -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). @@ -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.