Repository navigation
Releases
v0.10.0
Completes the ontology-evolution loop from #66. After ontos ontology approve, an operator lists the affected sources and re-ingests them one at a
time under their recorded ACL, with permissions rechecked before every write
and every decision in the Article-12 audit trail. Entity ids are now stable
and ACL-scoped, which fixes duplicate entities breaking ask (#121).
Read the upgrade notes.
Upgrade notes
-
Entity ids changed.
- New ingests store
Type:casefolded nameids. In a restricted document
they carry an@<digest>ACL suffix, for example
Company:acme corp@3f2a…. - Existing stores keep their old ids and need no migration: read-time
consolidation treats same-type, same-name entities as one. - Anything that matched on the model's raw ids, such as scripts or saved
exports, must switch to the new ids.
- New ingests store
-
One person, one node per name. Two different people with the same
name in one document are now one entity. -
New ingest warning. A source ingested under a different ACL than
before now gets a report warning, and its old facts are not superseded. -
Source registry.
- Ingest now records each
(source_id, acl_ref)pair, in the NetworkX
pickle and as:IngestedSourcenodes with a uniqueness constraint in
Neo4j. - The NetworkX file format is unchanged; older stores load with an empty
registry. - Sources ingested before this release must be ingested normally once
beforeontos reingestaccepts them (#125).
- Ingest now records each
-
ontos reingestneeds deployment configuration:ONTOS_AUDIT_DB_URLand an explicitONTOS_AUDIT_SIGNING_KEY;ONTOS_REINGEST_SOURCE_ROOTandONTOS_REINGEST_OPERATOR_SUBJECT;- a loopback Ollama;
- the operator must hold
ontology_approver, plusVIEWon the source's
ACL.
See
docs/scoped-reingest.md.
Added
-
ontos reingestre-extracts one registered source under its exact
recorded ACL (#66 M3-3, #120).- Authorization comes first:
ontology_approverandVIEWare checked
before the store is opened or any file is read. - The command loads only the selected
.txt,.mdor.pdf, with
O_NOFOLLOWand no directory scan. - Before every graph mutation it rechecks permissions and the source
registration. - Every decision is audited with keyed scope references, never raw
source ids or ACLs.
- Authorization comes first:
-
ONTOS_REINGEST_RECHECK_SECONDS(default0, maximum300) lets scoped
re-ingest reuse a successful per-write authorization recheck for a bounded
window instead of calling the authorization backend and source registry
before every graph mutation (#126). Denials are never reused, and the
window is recorded in the run's audit records. -
ontos ontology affected-sourceslists the sources whose rejected
evidence supports a signed migration record, split into those registered
forontos reingestand those not yet registered (#124). It requires
ontology_approver, only considers evidence the operator may VIEW, and
audits counts plus the same keyed scope referenceontos reingestrecords. -
docs/scoped-reingest.mdnow states that the source registry, not the
file, is the ACL trust anchor, and how to register sources ingested
before the registry existed (#127).
Changed — readable SVG graph export
-
New layout for
ontos export svg.- Entities sit in one column per type, ordered so relationships flow left to
right, and are colour-coded with a legend and a summary header. - Facts are curved, arrowed edges labelled with their predicate and source
document. Parallel facts fan out, and same-type relationships arc around
the column instead of cutting through the boxes between them. - Hover tooltips show provenance.
- Entities sit in one column per type, ordered so relationships flow left to
-
Unchanged. Output stays deterministic and dependency-free, and keeps
the samedata-*metadata. -
examples/demo/: a one-command local demo (run_demo.sh: ingest, ask,
an MCP agent, audit verification, SVG graph) and a deterministic
walkthrough ofas_of, ACL pruning and the audit chain (walkthrough.py).
The demo re-asks when a small local model returns an empty query plan.
Fixed — one real-world entity is one graph entity (#121, #122)
- Duplicate entities broke
ask. The extractor stored whatever entity ids
the model invented, and models are inconsistent: one #121 run gave a single
"Acme Corp" two ids in one document and a third id in another. The
resolver only compared entities within one document, and its merge records
were never applied, so the graph held several "Acme Corp" nodes and
"Who works at Acme Corp?" refused to guess. - Stable ids. Entity ids are now derived from
(type, casefolded name),
for exampleCompany:acme corp. The same entity converges within and
across documents, and rejected candidates use the same ids. - Scoped by ACL. A restricted document's ids carry a digest of its ACL,
so a same-named entity under another ACL stays a separate node (#48). The
pipeline no longer refuses such documents. - Read-time consolidation.
- When a seed matches several entities the caller can see, an exact name
or alias match wins. - Candidates with the same type and name are treated as one entity, which
fixes stores written before this change without re-ingesting. - Different types, or merely similar names, still refuse to guess.
- When a seed matches several entities the caller can see, an exact name
- Empty entities are rejected (#122). A triple whose subject or object
has an empty id, name or type is dropped with a generic warning, never
stored. - Behaviour changes.
- Two different people with the same name in one document are now one
entity (the exact-match rule). - Stored ids no longer match the model's raw ids.
- An exact seed name match is no longer treated as ambiguous.
- Ingesting a source under a different ACL than before now adds a
warning to the ingest report ("source also has facts under a
different ACL; they are not superseded by this ingest"). The other
ACL is never named. Before this change such a document either failed
with a cross-ACL entity conflict, when raw ids happened to collide, or
silently created a second copy.
- Two different people with the same name in one document are now one
v0.9.0
Ontos can now evolve its ontology under review (#66 M3). An operator holding
the new ontology_approver role approves one evidence-backed suggestion with
ontos ontology approve. The change is recomputed from candidates the
approver may view, recorded in the Article-12 audit trail, and written out as
a new, never-overwritten ontology version and a signed migration record.
Nothing is activated automatically.
Once the operator activates a version, verified migrations project historical
facts onto it on every read surface. LLM-assisted suggestions are now
reproducible and pinned to a model digest, behind one explicit trust
boundary. Read the upgrade notes.
Upgrade notes
- Migrations are opt-in. They are off unless
ONTOS_MIGRATIONS_DIRand
ONTOS_ONTOLOGY_HISTORY_DIRare both set; setting only one is an error.
With them on:- every read path hides facts that have no ontology stamp, a different
ontology id, or no verified path to the active version; - the privileged
--include-acl-maskexport is exempt; - see
docs/ontology/m3-1-migrations.mdbefore enabling on an existing
graph.
- every read path hides facts that have no ontology stamp, a different
- Migration records must be signed. Verified reads refuse a migration
without a validapproval_signature, so create migrations with
ontos ontology approverather than by hand. Signatures use a key derived
from the audit signing key, which means rotating
ONTOS_AUDIT_SIGNING_KEYrequires re-signing existing migrations. - New
ontology_approverrelation.ontology_reviewerand
audit_exporterdon't imply it. Grant it explicitly in OpenFGA. - M2b suggestions need the model installed.
--llm-modelresolves the
model digest from the local Ollama before reading evidence and fails if the
model isn't pulled. - Suggestion output and audit shape changed.
generator_versionis nowmodel@sha256:<digest>.- Outcome records add
prompt_schema_sha256andskipped_count, and a
cancelleddecision. - Refused backends appear with
generator_trust: "refused". - CLI JSON gains a
generationblock. - Combined output is sorted.
- Excess model proposals count once in
invalid_count.
- Stricter
OntologySuggestion.- Labels must be identifiers of at most 64 characters.
- LLM-assisted kinds require a lower_snake_case
observed_predicateand
extractor_versions. add_patternrejectsobserved_predicate.
- Python API changes.
require_approved_suggestion_backendreturns an
ApprovedSuggestionBackendtoken, not the backend.- The endpoint policy moved to
ontos.llm.local_endpoint; the old
ontos.ontology.suggestion_endpointpath still works.
- Additive.
Provenance.mapped_from_predicateappears in MCP responses
and every export format. NetworkX stores and.pklsnapshots saved by
0.8.0 load correctly.
Added — audited ontology approval and signed migrations (#66 M3-2, #117)
ontos ontology approve --acting-on-behalf-of SUBJECT, run by a
trusted local operator. It takes--base-version,--new-version, a
--change-fileholding exactly one change (add_pattern,
map_to_existingornew_relation_type),--acl-refand two output
paths.- Authorization. It requires
ontology_approverplus VIEW on the
supporting evidence. The change is recomputed only from candidates the
approver may view, and an approver without VIEW gets the same "No such
suggestion" as for a nonexistent one. - Audit-first and fail-closed. The request is audited before any
candidate is read, and permissions are rechecked before granting and again
before publishing.approval_grantedis persisted before either file is
written, and evidence references are HMAC-keyed. - Safe outputs. Neither file may already exist, the base version must
match the active ontology, and rollback removes only files this run
created. - Signed migration records. Each record carries an HMAC over its
canonical form, keyed with a purpose-specific subkey of the audit signing
key. The MCP server,ontos query, exports and the executor refuse
migrations that are unsigned or tampered with. Verification needs no audit
lookup, so retention pruning of the approval event doesn't invalidate a
migration. - Suggestions skip already-mapped predicates. Suggestions and approvals
share the final validation pass.
Changed — one trust boundary and one validation path for M2b (#90)
- Explicit approval registry.
APPROVED_SUGGESTION_BACKENDSlists the
exact classes allowed to receive candidate evidence; subclasses and
spoofed objects are still refused. Backends prove a local transport
through a publicattest_local_transport(). The gate no longer reads
Ollama internals, so a sovereign Scribe adapter can be added without
editing the gate. - Checked once per request.
require_approved_suggestion_backend
returns a sealedApprovedSuggestionBackendthat only the gate can mint.
The pipeline and request layers accept that token instead of repeating
the sovereignty check (previously up to four times per request). - No import cycle. The loopback endpoint policy moved to
ontos.llm.local_endpoint, with a re-export at the old path. - One label rule, one final validation.
- Every relation-label check uses
ontos.ontology.labels; the regex was
defined five times before. - The ontology-consistency filter now runs once, over M2a and M2b output
together. map_to_existingcan now target an existing uppercase relation such as
WORKS_AT. Membership in the ontology is what makes a target safe, so it
is no longer rejected for not being lower_snake_case.
- Every relation-label check uses
Fixed — M2b suggestion correctness and CLI output (#90)
- Stable order. M2a and M2b suggestions are sorted together by
(acl_ref, kind, pattern, observed_predicate), instead of following the
model's response order. - Stricter
OntologySuggestion.- Every label must be an identifier of at most 64 characters, which rejects
values such asDROP TABLE x;. map_to_existingandnew_relation_typerequire a lower_snake_case
observed_predicateandextractor_versions.add_patternrejectsobserved_predicate.- A new relation must keep the observed predicate.
- Every label must be an identifier of at most 64 characters, which rejects
- Skipped evidence is reported. Candidates whose predicate isn't
lower_snake_case (e.g.employedBy) are counted asskipped_countin the
audit and the CLI, instead of being dropped silently. Ontology loading is
unchanged. - CLI
generationblock. Shows mode, generator id and pinned version,
invalid_count,skipped_countand the outcome auditquery_id. - Specific failure hints. The CLI distinguishes connection refused, a
model that isn't installed (or a 404), timeouts, an oversized prompt and a
refused backend. Response bodies are never printed.
Fixed — M2b suggestion audit and reproducibility (#90)
- Cancellation is audited. A cancelled model call (Ctrl-C, task cancel)
now writes acancelledoutcome record before re-raising. The trail no
longer ends atrequest_started. - Pinned model version.
generator_versionis nowmodel@sha256:<digest>,
resolved once per run from the local Ollama/api/tagsbefore any evidence
is read. Outcome records also carryprompt_schema_sha256, covering the
system prompt, response schema and sampling options. A model that isn't
installed fails before candidates are read. - Reproducible generation. Suggestion requests send
temperature=0,
seed=0and an explicitnum_ctx. A prompt that wouldn't fit is refused
before sending, and a prompt Ollama reports as filling the window fails the
request instead of returning truncated results. - Refused backends are named. A refused backend appears in the outcome
record asgenerator_idwithgenerator_trust: "refused", so a trust
refusal is distinguishable from a model failure. invalid_countis consistent. A response padded with excess proposals
counts as one invalid response, like any other.
Added — versioned ontologies and verified migrations (#66 M3-1, #111)
- Predicate mappings. Ontology YAML gains
predicate_mappings, each
scoped to one subject type, observed predicate and object type. The
extractor normalises a mapped predicate before validation and records the
original inProvenance.mapped_from_predicate. - Declarative migration records for additive changes (
add_pattern,
map_to_existing,new_relation_type), with non-overwriting generation of
versioned ontology and migration files. - Verified migrations.
ONTOS_MIGRATIONS_DIRand
ONTOS_ONTOLOGY_HISTORY_DIRload a migration chain. The chain must be
complete and acyclic and end at the active version, and every step is
verified against the historical ontology files. Misconfiguration stops the
server at boot. - Old stores still load. NetworkX stores and
.pklsnapshots saved
beforemapped_from_predicateexisted load correctly.
Fixed — verified migrations apply to every read surface (#112)
- The gap. M3-1 hid facts without a verified migration path from
ask
andontos queryonly. The MCPsearch,traverse,explainand
provenancetools andontos exportstill returned them. - Every read surface now projects through the same verified registry.
- Excluded facts can't bridge traversals or
--entityexport
neighbourhoods. - Exports drop untyped endpoints that only excluded facts name.
provenanceanswersnullfor an excluded fact.searchrefetches to fillk.
- Excluded facts can't bridge traversals or
- Nothing reported back. Audit records name the ontology results were
projected onto, and never what was excluded. - Exempt: the privileged
--include-acl-maskexport, which audits
stored state.
v0.8.0
ontos serve now keeps its Article-12 audit trail in Postgres, and
ontos query and ontos ingest write audit records too. Every tool
failure is audited, and nothing runs when the audit store is unavailable.
Store writes can no longer rewrite fact history, and supersession is
atomic. Read paths hide facts and exported entities that would reveal
restricted entities. Neo4j reads are deterministic and no longer
enumerate every path. ask can run under ontos serve with a local
Ollama planner, and ontology suggestions can be LLM-assisted from a local
model (#66 M2b). Read the upgrade notes: this release has breaking
changes.
Upgrade notes
- Breaking:
ONTOS_ENV=prodrequiresONTOS_AUDIT_DB_URL. Without
it,ontos serverefuses to boot. The Helm chart already sets it from
theontos-audit-dbSecret. - Breaking: audit is fail-closed.
- An MCP tool call whose audit record can't be written fails with
audit unavailable. A transport rejection (401/403) becomes a 500. ontos queryandontos ingestexit with code 1 before running if
the audit store can't be opened.
- An MCP tool call whose audit record can't be written fails with
- Async database URLs only. Audit DB URLs must use an async driver:
postgresql+asyncpg://(install the newpostgresextra; the image
includes it) orsqlite+aiosqlite://..env.examplepreviously listed
sync URLs that were always rejected. - Bounded arguments. MCP
searchkmust be 1–100 andtraverse
depth1–10. Values outside those ranges are rejected and audited. - Breaking for custom
GraphStoreimplementations.add_factmust reject an existing id (FactAlreadyExistsError).close_factmust refuse an already-closed fact (FactNotOpenError).- Stores must implement the new atomic
supersede(new_fact, closes),
which ingest now calls.
- Fewer results by design. Facts whose endpoint entities the caller
can't see are no longer returned (#91). Ordinary exports omit untyped
entities that no exported fact names (#100);--include-acl-mask
exports are unchanged. askerrors.askis disabled untilONTOS_PLANNER_BACKEND=ollama
andONTOS_ONTOLOGY_PATHare set. Planning failures return a fixed
message instead of the planner's error text.- Ranking changes. Search ordering is now deterministic. Traversals
return each fact once, and executor scores use true hop distances.
Expect rankings to differ from 0.7.0. - New
ontos query --acting-on-behalf-of SUBJECT. Without it,ontos querystill sees public facts only.
Performance — Neo4j traverse no longer enumerates every path (#104)
- The problem.
traversematched(start)-[:RELATES*1..depth]-(end)and
deduplicated relationships afterwards. Variable-length matching enumerates
every path, which grows exponentially with depth on dense graphs. - The fix. It now expands one hop per query, breadth-first like NetworkX,
inside a single read transaction. Each relationship is visited once per
level, and the ACL, validity and relation filters apply at every hop. - Same results. A fact is reachable through a visible path within
depth
hops exactly when one of its endpoints is reached withindepth - 1, so the
result set is unchanged. - Benchmark. On a 40-node clique at depth 4 the traversal takes 2.6s.
Before this change the run didn't finish within the 4-minute limit.
Fixed — executor reports each fact's real hop distance (#103)
- Wrong distances.
DeterministicExecutorstamped every fact a traversal
step returned with one hop. WithTraversalStep(depth=3), a fact three
hops from the seed scored like a direct neighbour, andhops_from_seed
was wrong. - The fix. Each fact's distance from the step's start is now computed
over the step's results, following the step's direction, and adds up across
steps. Distances are computed before migration translation, so a fact the
migration drops can't make the facts beyond it look unreachable.
Fixed — storage reads are deterministic and match across backends (#102)
- Neo4j
searchappliedLIMIT kto an unordered match, so the top-k set
could change between calls. It now scores matches exactly like NetworkX
(exact field match 1.0, otherwise by match length). Ties go to the oldest
ingested_at, thenfact_id. A raw node's placeholder name no longer
affects the score. - NetworkX
traverse(direction="both")returned an edge once from each
end. It now returns each fact once. - Ordering. Both backends return traversals in the same ingest order.
Fixed — ask works under ontos serve and hides planner errors (#101)
askcan now be enabled. Nothing ever built a planner for the server,
soaskalways answered "no planner configured". Set
ONTOS_PLANNER_BACKEND=ollamawithONTOS_PLANNER_MODEL,
ONTOS_PLANNER_URL,ONTOS_PLANNER_TIMEOUTandONTOS_ONTOLOGY_PATH.
Only the local Ollama backend is offered, so planning stays inside the
customer's VPC. An unknown backend, or a missing ontology, stops the server
at boot.- Planner errors are no longer echoed. A failed plan used to return
str(exc)to the caller and write it into the audit record; that text comes
from the model or provider. Callers now get "the question could not be
planned". The audit record and logs carry only the error type.
Security — exports no longer reveal entities named only by forbidden facts (#100)
- The leak.
add_factcreates an untyped endpoint node for every id it
references.scan(), which everyontos exportformat uses, treated those
ACL-less nodes as public. An export therefore dropped a restricted fact but
still listed its endpoint, which proves the hidden fact exists. This was the
same leak #82 and #91 fixed for search, traversal and entity search. - The fix, in NetworkX and Neo4j. An untyped node is now exported only
when a fact or merge record in the same scan names it. Typed entities follow
their own ACL as before. The privileged--include-acl-maskexport is
unchanged.
Fixed — ontos query and ontos ingest are audited (#94)
- One Article-12 record per invocation. Both commands touched the graph
without writing any record. They now write one each, success or failure, to
ONTOS_AUDIT_DB_URL(the default is the local SQLite chain, as with
ontos export). The record is written before results are printed.ontos queryrecords the plan, the returned fact ids and the
authorization decisions.ontos ingestrecords the ids of the facts it wrote, plus counts,
extractor and ontology versions. Warnings and errors are left out because
they can quote document text.
- Fail closed. If the audit store is unavailable, neither command plans,
extracts or reads anything. ontos query --acting-on-behalf-of SUBJECT. Returns only the facts
SUBJECT may view, resolved through the configured authz backend. The subject
is asserted by the local operator, recorded asoperator_asserted, and is
not authenticated. Without the flag, queries still see public facts only.- The dev signing-key warning goes to stderr, so the JSON on stdout stays
parseable.
Fixed — store writes never rewrite history (#95)
close_factno longer rewrites a closed fact. Closing an already-closed
fact used to move itst_invalidand replacesuperseded_byin both
backends. It now raisesFactNotOpenError. Closing a missing fact is still
a no-op.- A duplicate
add_factis rejected in both backends with
FactAlreadyExistsError. Before this, NetworkX replaced the fact in place
and Neo4j created a second edge with the samefact_id. - Supersession is atomic. The new
GraphStore.supersede(new_fact, closes)
adds the new fact and closes the old ones together; ingest now uses it.
Neo4j runs it in one transaction. NetworkX validates everything before
writing. A failed supersede leaves the store unchanged, where a failed
close used to leave two active facts in one scope. - Shared tests. The NetworkX compliance tests and the Neo4j integration
tests run the same checks.
Fixed — ontos serve persists its audit trail (#93)
- Article-12 records no longer vanish on restart.
ontos serve(live and
--snapshot) always used the in-memory audit sink and never read
ONTOS_AUDIT_DB_URL, though the Helm chart sets it. With the variable set,
the server now writes to the persistent hash-chained sink
(PostgresAuditEmitter) and creates its table at startup. Without it,
records stay in memory (dev only), andONTOS_ENV=prodrefuses to boot. - Tool calls, transport rejections (401/403) and the
audittool all use
the persistent sink. The request path now awaits the async sink. - Fail closed. If an audit record cannot be written, the call fails with
audit unavailableand returns no data. A transport rejection becomes a
500. Sink error text is never returned or logged. - Records carry the real version.
model_versions.runtimeis now the
package version, replacing the hard-coded0.0.1. - New
postgresextra (asyncpg), included in the container image.
Before this the image could not connect to a Postgres audit DB.
.env.examplenow uses async drivers (sqlite+aiosqlite://,
postgresql+asyncpg://); the sync URLs it listed were always rejected.
Fixed — every MCP tool failure is audited
- Some tool failures left no Article-12 record. After authentication, a
malformedas_of, a malformedfact_id/query_id, an authz backend outage
or a store error escaped the tool with no audit record, against the
audit-first rule. Every tool failure now writes one record with the decision
invalid_request,authorization_errororerror. - Callers get a safe message. Errors return a generic
ToolErrorand never
echo backend text; only the error type is logged (mcp-tool-failed). - **
searchkis bo...