engine 0.4.44: W7 NLQ typed-plan compiler — question → sealed, provenance-carrying plan

[mdheller]

The W7 NLQ typed-plan compiler (ts/src/nlq.ts): a natural-language question becomes a sealed, provenance-carrying plan over a registry of typed Semantic Actions — without executing anything.

question
  → deterministic tokenization (spans preserved)
  → ontology-annotated tokens (pluggable annotators)
  → side-effect-free restricted search over the typed action registry
  → sense-metric-ranked variant plans
  → winner sealed against the graph snapshot

The contract is vendored and tamper-evident

SemanticAction.json from SourceOS-Linux/sourceos-spec (PR #210, ee7e43a4) lands byte-identical at ontology/semantic-action/ and is embedded into ts/src/semantic-action-data.ts by scripts/gen-semantic-action.mjs — the same way KKO ships, because tsup bundles to one file per format and there is no runtime asset to read.

Its sha256 fd01c834… is asserted at import: a drifted or hand-edited contract fails LOUDLY at load, never silently at plan time. The digest is sealed into every receipt, so a plan names the exact contract it was compiled against. ActionRegistry.declare validates against the schema's own bytes, plus the two invariants the contract documents but JSON Schema cannot express (input names unique within an action; every constraint subject resolving to a declared input or output).

Typed unification, not prompting

An annotation or output of type T binds a slot declared U exactly when isA(T, U) in the AtomSpace TypeLattice — so :ContactList satisfies a :List slot by subsumption, and nothing satisfies a slot it is not under. Cardinality is enforced (a set never fills a single-valued slot) and every binding records a SubsumptionWitness. instanceOf is necessarily approximated by the same static check at search time, since no values exist yet — documented in code, not silently conflated.

Three normative rules

1. Purity. Search never mutates the store — store.version() is identical before and after, proved by test.
2. Effects are proposed, never taken. An effect-request action is a leaf of the dataflow: never offered as an input provider (consuming its output is what would imply running it), so it only ever appears as the plan root carrying an EffectRequestProposal{status:'proposed'}. Its own arguments may still be computed by pure actions — computing an argument is not taking the effect. The MPCC lifecycle (EffectRequest → EffectDecision → EffectRecord) is never bypassed.
3. Mentions are not values. A concept in the text is evidence a type is in play, not that a value is in hand, so non-literal slots must be filled by an action or a registry default. This is what forces "contact lists in my org" to decompose into GetContactLists ← GetOrganization instead of collapsing into one node with an imaginary argument.

The creativity penalty IS the admissibility discount

coverage · groundedness · similarity, composite with explicit weights carried in the result (0.5 / 0.3 / 0.2).

Every plan node not grounded in a token span or a registry default is an invention, so it is routed through admitClaim (merged in 0.4.43) as a model-generated claim and its weight becomes the admissibility discount (×0.5) — one mechanism, not a parallel heuristic. Under admissibility: { allowOpinion: false } an invented node is inadmissible and the whole variant is dropped, because an excluded claim carries weight 0 and "must not enter the reasoning context at all". A question the registry cannot serve then yields no variants rather than a guess.

Sealed exactly like enrich / explore: sha256 over ranked output + {seq,nodes,edges} snapshot + pinned contract digest, where seq is the store's monotonic logical clock. Same inputs against the same graph state ⇒ byte-identical seal.

Evidence (EBA-style fixture)

Toy CRM registry — GetContactLists / GetOrganization / GetMailingsByList / FindListByName / NumberOf / Count (polymorphic over subClassOf :List) / SendMailing (effect-request).

question	winner	composite
"show me all contact lists in my org"	GetContactLists ← GetOrganization	1.000
"how many mailings on list Acme"	NumberOf → GetMailingsByList → FindListByName("Acme")	1.000
"send mailing to list Acme"	SendMailing[effect proposed] ← FindListByName("Acme")	1.000

The polymorphic Count(:List) ← FindListByName(:ContactList) variant is produced (proving subsumption binding where the direct type differs) and is correctly ranked below the winner on coverage — it never consumes "mailings".

Gates

• Full suite 371/371 (was 347) — +24 new tests, none broken.
• npm run typecheck clean · npm run check:dist exit 0 · dist rebuilt and smoke-tested from the bundle.
• Zero upstream drift at push.

Docs: docs/specs/15_NLQ_Typed_Plan_Compiler_v0_1.md + spec-index entry.

Reviewer note — one interpretation call

The brief said effect-request actions may appear "ONLY as plan leaves". Taken as no children, such an action could never receive a computed argument, which makes the feature vacuous. I implemented the dataflow reading — its output is never consumed, so it can only be the plan root — which is the invariant that actually protects search-time purity, while its arguments may be computed by pure actions. Flagging it explicitly in case the stricter reading was intended.