@equationalapplications/core-llm-wiki 6.0.1 → 6.2.0

package/README.md

@@ -582,6 +582,86 @@ In **Strict** and **Emergent** modes, librarian and ingest JSON may include type
 
 See the design spec: [`docs/superpowers/specs/2026-06-23-per-entity-seeded-ontology-design.md`](https://github.com/equationalapplications/expo-llm-wiki/blob/main/docs/superpowers/specs/2026-06-23-per-entity-seeded-ontology-design.md).
 
+### Ontology type inheritance
+
+`OntologyNodeType` accepts an optional `parent_type` field for **one-level type inheritance** — the building block for polymorphic queries like "all CreativeWorks" without deep, multi-level hierarchies.
+
+```ts
+// packages/core/src/types.ts
+export interface OntologyNodeType {
+  type: string;
+  description: string;
+  /** Optional parent type slug. One level only — the parent must exist in the
+   *  same manifest and must not itself declare a `parent_type`. */
+  parent_type?: string;
+}
+```
+
+A concrete type declares `parent_type: '<parent-slug>'`; the parent must be a top-level node in the same manifest. A `design_spec` node with `parent_type: 'creativework'` is treated as both itself *and* a `creativework` during edge matching.
+
+#### Inheritance rules (strictly enforced)
+
+`validateManifest` enforces the **one-level invariant** at every persist and read (`entity_manifests.manifest_json` is `JSON.parse`d on every read, so validation runs on the read path too). Violations throw:
+
+| Condition | Error |
+|-----------|-------|
+| `parent_type` references an unknown slug | `Parent type not found: <slug>` |
+| `parent_type` equals the node's own slug | `Self-parent: <type>` |
+| The referenced parent also declares a `parent_type` | `Parent chain too deep: <a> → <b> → <grandparent>` |
+| `parent_type` is present but blank (`''` / whitespace) or non-string (`number`, `null`, `object`) | `Ontology parent_type must be a non-empty string when present: <type>` |
+
+Two consequences worth knowing:
+
+- The depth check rejects **2-cycles** (`a → b → a`) which a self-parent check alone would miss.
+- A *present* `parent_type` key is required to be a usable string; an *absent* key (`undefined`) is fine and means "no parent". This is the same rule core applies to blank slugs elsewhere (`Ontology node type slug must be non-empty`).
+
+Parent types are **instantiable** — a fact may be classified as bare `creativework`, and `resolveNodeType('creativework')` returns `'creativework'` normally. There is no `abstract` flag; if you want a parent to stay abstract, write the description to steer classification toward the concrete children.
+
+#### Edge matching (symmetric, exact-first)
+
+Edge matching is parent-aware on **both** sides and routes through a single primitive, `typeSatisfies(declaredType, concreteType, manifest)`:
+
+- `declaredType === concreteType` (case-insensitive) → **exact match**, short-circuits before the node lookup. Manifests with no `parent_type` behave bit-for-bit as before.
+- Otherwise: looks up `concreteType`'s definition in the manifest and returns `true` if its `parent_type` equals `declaredType`. One hop only — `typeSatisfies` never recurses.
+
+`typeSatisfies` is used at four gates — `validateInlineEdges` (source), `OntologyService.resolveEdges` (source and target, via two-pass), `IngestionService.upsertGraph` (source) — so a parent-satisfied edge that validates will also persist.
+
+**Targets resolve exact-first.** When resolving an edge against a target fact, `OntologyService.resolveEdges` runs two passes over candidate defs:
+
+```ts
+// Packages/core/src/services/OntologyService.ts (abridged)
+const targetType = (target.okf_type ?? '').trim().toLowerCase();
+const def = candidates.find(d => d.target_type.trim().toLowerCase() === targetType)
+  ?? candidates.find(d => typeSatisfies(d.target_type, targetType, manifest));
+```
+
+The exact pass runs first, so a `design_spec` target with both `about creativework → creativework` and `about creativework → design_spec` declared resolves to the **narrower** row — array order never decides which pass wins. Ties within a single pass are immaterial: only `def.type` is read off the winning def, and `validateManifest` already rejects a manifest whose triples spell one edge name with different casing, so every candidate within a pass yields a byte-identical edge row.
+
+> **Accepted cost:** declaring `→ creativework` now admits every child of `creativework`, and there is no way to say "the parent type only." A type that needs an exact-only target must not be given children.
+
+#### Emergent prompt schema
+
+In `emergent` mode the LLM may propose new types via `ontology_updates`. The prompt schema (`EMERGENT_EXTRA` in `packages/core/src/prompts/ontology.ts`) advertises the optional `parent_type` so emergent proposals can suggest children of an existing type:
+
+```json
+"ontology_updates": {
+  "node_types": [{ "type": "slug", "description": "...", "parent_type": "optional existing slug" }],
+  "edge_types": [{ "type": "slug", "source_type": "...", "target_type": "...", "description": "..." }]
+}
+```
+
+The rest of the manifest reaches the LLM unchanged — `buildPromptContext` does `JSON.stringify(manifest, null, 2)`, so an established manifest's `parent_type` fields appear verbatim alongside `type` and `description`.
+
+Emergent proposals are **untrusted input**: `mergeOntologyUpdates` drops any `parent_type` (rather than throwing) when it is a non-string, blank, unresolvable, self-referential, or whose referenced parent already declares its own parent. The lenient merge contract keeps malformed LLM proposals from aborting an ingest transaction. Changing an established type's parent is a `setOntologyManifest` operation.
+
+#### Backwards compatibility
+
+`parent_type` is optional and manifests persist as a whole JSON blob in `entity_manifests.manifest_json`. Existing manifests without the field validate identically; no SQLite migration is needed. `setOntologyManifest` rejects a two-level chain at the public API boundary, so callers cannot accidentally introduce an unenforced chain through a typo.
+
+`typeSatisfies` is intentionally **not** re-exported from the package's public surface (`packages/core/src/index.ts`). No host needs the primitive to author or validate a manifest; publishing it would freeze an internal matching rule into the package's public surface.
+
+See the design spec: [`docs/superpowers/specs/2026-08-28-ontology-parent-field-spec.md`](https://github.com/equationalapplications/expo-llm-wiki/blob/main/docs/superpowers/specs/2026-08-28-ontology-parent-field-spec.md).
+
 ### Ontology backfill
 
 Facts that enter the store without passing through the librarian (synced-down
@@ -1131,6 +1211,7 @@ The flowchart shows:
 | [@equationalapplications/core-llm-tools](https://github.com/equationalapplications/expo-llm-wiki/blob/main/packages/core-llm-tools/README.md) | Gemini tool schemas and capability injector |
 | [@equationalapplications/core-okf](https://github.com/equationalapplications/expo-llm-wiki/blob/main/packages/okf/README.md) | Zero-dependency Open Knowledge Format (OKF) v0.1 + v0.2 primitives — parse and produce interoperable knowledge bundles. |
 | [@equationalapplications/schema-org-llm-wiki](https://github.com/equationalapplications/expo-llm-wiki/blob/main/packages/schema-org/README.md) | Curated schema.org warm-agent ontology manifest |
+| [@equationalapplications/schema-software-org](https://github.com/equationalapplications/expo-llm-wiki/blob/main/packages/schema-software-org/README.md) | Software-organization executive ontology manifest — 17 node types, 40 edges, warm-agent superset, data-only |
 
 ## OKF v0.2 conformance (llm-wiki/2)
 

package/dist/{chunk-HREQ6F6Z.mjs → chunk-YEESP6J2.mjs}

@@ -190,6 +190,17 @@ function resolveEdgeDefinitions(rawEdgeType, manifest) {
 function edgeTripleKey(type, sourceType, targetType) {
   return `${type.trim().toLowerCase()}|${sourceType.trim().toLowerCase()}|${targetType.trim().toLowerCase()}`;
 }
+function typeSatisfies(declaredType, concreteType, manifest) {
+  const concrete = concreteType.trim().toLowerCase();
+  const declared = declaredType.trim().toLowerCase();
+  if (!concrete || !declared) return false;
+  if (declared === concrete) return true;
+  const def = (manifest.node_types ?? []).find(
+    (n) => typeof n?.type === "string" && n.type.trim().toLowerCase() === concrete
+  );
+  const parent = typeof def?.parent_type === "string" ? def.parent_type.trim().toLowerCase() : "";
+  return parent !== "" && parent === declared;
+}
 function validateManifest(manifest) {
   const nodeSlugs = /* @__PURE__ */ new Set();
   for (const node of manifest.node_types ?? []) {
@@ -199,6 +210,28 @@ function validateManifest(manifest) {
     if (nodeSlugs.has(key)) throw new Error(`Duplicate node type: ${type}`);
     nodeSlugs.add(key);
   }
+  const parentOf = /* @__PURE__ */ new Map();
+  for (const node of manifest.node_types ?? []) {
+    const parent = typeof node.parent_type === "string" ? node.parent_type.trim().toLowerCase() : void 0;
+    parentOf.set(node.type.trim().toLowerCase(), parent);
+  }
+  for (const node of manifest.node_types ?? []) {
+    if (node.parent_type === void 0) continue;
+    if (typeof node.parent_type !== "string" || !node.parent_type.trim()) {
+      throw new Error(`Ontology parent_type must be a non-empty string when present: ${node.type}`);
+    }
+    const parentSlug = node.parent_type.trim().toLowerCase();
+    if (parentSlug === node.type.trim().toLowerCase()) {
+      throw new Error(`Self-parent: ${node.type}`);
+    }
+    if (!nodeSlugs.has(parentSlug)) {
+      throw new Error(`Parent type not found: ${node.parent_type}`);
+    }
+    const grandparent = parentOf.get(parentSlug);
+    if (grandparent) {
+      throw new Error(`Parent chain too deep: ${node.type} \u2192 ${node.parent_type} \u2192 ${grandparent}`);
+    }
+  }
   const edgeKeys = /* @__PURE__ */ new Set();
   const edgeNames = /* @__PURE__ */ new Map();
   for (const edge of manifest.edge_types ?? []) {
@@ -222,18 +255,38 @@ function validateManifest(manifest) {
     }
   }
 }
+function buildDeclaresParentIndex(nodes) {
+  const declaresParent = /* @__PURE__ */ new Map();
+  for (const n of nodes) {
+    const slug = typeof n?.type === "string" ? n.type.trim().toLowerCase() : "";
+    if (!slug || declaresParent.has(slug)) continue;
+    declaresParent.set(slug, n?.parent_type !== void 0);
+  }
+  return declaresParent;
+}
 function mergeOntologyUpdates(current, updates) {
   const node_types = [...current.node_types];
   const edge_types = [...current.edge_types];
   const nodeSlugs = new Set(node_types.map((n) => n.type.trim().toLowerCase()));
   const edgeKeys = new Set(edge_types.map((e) => edgeTripleKey(e.type, e.source_type, e.target_type)));
   const edgeNames = new Map(edge_types.map((e) => [e.type.trim().toLowerCase(), e.type.trim()]));
+  const declaresParent = buildDeclaresParentIndex([
+    ...current.node_types,
+    ...updates.node_types ?? []
+  ]);
   for (const node of updates.node_types ?? []) {
     const type = node?.type?.trim();
     if (!type) continue;
     const key = type.toLowerCase();
     if (nodeSlugs.has(key)) continue;
-    node_types.push({ type, description: String(node.description ?? "") });
+    const rawParent = typeof node?.parent_type === "string" ? node.parent_type.trim() : "";
+    const parentSlug = rawParent.toLowerCase();
+    const keepParent = parentSlug !== "" && parentSlug !== key && declaresParent.get(parentSlug) === false;
+    node_types.push({
+      type,
+      description: String(node.description ?? ""),
+      ...keepParent ? { parent_type: rawParent } : {}
+    });
     nodeSlugs.add(key);
   }
   for (const edge of updates.edge_types ?? []) {
@@ -270,7 +323,7 @@ function validateInlineEdges(sourceType, _targetType, edges, manifest, opts) {
       continue;
     }
     const defs = resolveEdgeDefinitions(edge.edge_type, manifest);
-    const match = defs.find((d) => d.source_type.toLowerCase() === sourceType.toLowerCase());
+    const match = defs.find((d) => typeSatisfies(d.source_type, sourceType, manifest));
     if (!match) {
       if (strict) throw new WikiStrictOntologyViolation(entityId, "edge", edge.edge_type);
       continue;
@@ -1946,7 +1999,7 @@ var IngestionService = class {
       }
       const sourceType = sourceIdToType.get(edge.sourceId);
       const candidates = (manifest.edge_types ?? []).filter(
-        (d) => d.type.toLowerCase() === edge.type.toLowerCase() && d.source_type.toLowerCase() === (sourceType ?? "").toLowerCase()
+        (d) => d.type.toLowerCase() === edge.type.toLowerCase() && typeSatisfies(d.source_type, sourceType ?? "", manifest)
       );
       const match = candidates[0];
       if (!match) {
@@ -4566,6 +4619,6 @@ var WriteService = class {
   }
 };
 
-export { BaseRepository, DEFAULT_CHUNK_OVERLAP, DEFAULT_MAX_CHUNK_LENGTH, EmbeddingService, HEAL_ANCHORS_PER_CANDIDATE, HEAL_BATCH_SIZE, HEAL_MAX_FACT_BODY_CHARS_L3, HEAL_MAX_TASKS, HEAL_RECHECK_MS, HOOK_TIMEOUT_MARKER, ImportExportService, IngestionService, JobManager, MaintenanceService, MetadataRepository, ONTOLOGY_BACKFILL_BATCH_SIZE, ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS, ONTOLOGY_BACKFILL_RECHECK_MS, ONTOLOGY_BACKFILL_SYSTEM_PROMPT, PromptService, PrunePartialFailureError, RetrievalService, SearchService, WikiBusyError, WikiDuplicateHashError, WikiIngestEmptyError, WikiParseError, WikiSourceRefHashCollision, WikiStrictOntologyViolation, WikiTransactionError, WriteService, __privateAdd, __privateGet, __privateSet, chunkText, configureRandomSource, emptyManifest, entitySummaryMetaKey, extractSqliteCode, generateId, normalizeSourceHash, normalizeSourceRef, normalizeTitleKey, parseEmbedding, resolveEdgeDefinitions, resolveNodeType, safeSlice, validateInlineEdges, validateManifest };
-//# sourceMappingURL=chunk-HREQ6F6Z.mjs.map
-//# sourceMappingURL=chunk-HREQ6F6Z.mjs.map
+export { BaseRepository, DEFAULT_CHUNK_OVERLAP, DEFAULT_MAX_CHUNK_LENGTH, EmbeddingService, HEAL_ANCHORS_PER_CANDIDATE, HEAL_BATCH_SIZE, HEAL_MAX_FACT_BODY_CHARS_L3, HEAL_MAX_TASKS, HEAL_RECHECK_MS, HOOK_TIMEOUT_MARKER, ImportExportService, IngestionService, JobManager, MaintenanceService, MetadataRepository, ONTOLOGY_BACKFILL_BATCH_SIZE, ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS, ONTOLOGY_BACKFILL_RECHECK_MS, ONTOLOGY_BACKFILL_SYSTEM_PROMPT, PromptService, PrunePartialFailureError, RetrievalService, SearchService, WikiBusyError, WikiDuplicateHashError, WikiIngestEmptyError, WikiParseError, WikiSourceRefHashCollision, WikiStrictOntologyViolation, WikiTransactionError, WriteService, __privateAdd, __privateGet, __privateSet, chunkText, configureRandomSource, emptyManifest, entitySummaryMetaKey, extractSqliteCode, generateId, normalizeSourceHash, normalizeSourceRef, normalizeTitleKey, parseEmbedding, resolveEdgeDefinitions, resolveNodeType, safeSlice, typeSatisfies, validateInlineEdges, validateManifest };
+//# sourceMappingURL=chunk-YEESP6J2.mjs.map
+//# sourceMappingURL=chunk-YEESP6J2.mjs.map