Repository navigation
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.