Skip to content

v0.9.0

Choose a tag to compare

@github-actions github-actions released this 09 Nov 11:49
· 25 commits to main since this release
d93b3fb

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_DIR and
    ONTOS_ONTOLOGY_HISTORY_DIR are 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-mask export is exempt;
    • see docs/ontology/m3-1-migrations.md before enabling on an existing
      graph.
  • Migration records must be signed. Verified reads refuse a migration
    without a valid approval_signature, so create migrations with
    ontos ontology approve rather than by hand. Signatures use a key derived
    from the audit signing key, which means rotating
    ONTOS_AUDIT_SIGNING_KEY requires re-signing existing migrations
    .
  • New ontology_approver relation. ontology_reviewer and
    audit_exporter don't imply it. Grant it explicitly in OpenFGA.
  • M2b suggestions need the model installed. --llm-model resolves 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_version is now model@sha256:<digest>.
    • Outcome records add prompt_schema_sha256 and skipped_count, and a
      cancelled decision.
    • Refused backends appear with generator_trust: "refused".
    • CLI JSON gains a generation block.
    • 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_predicate and
      extractor_versions.
    • add_pattern rejects observed_predicate.
  • Python API changes.
    • require_approved_suggestion_backend returns an
      ApprovedSuggestionBackend token, not the backend.
    • The endpoint policy moved to ontos.llm.local_endpoint; the old
      ontos.ontology.suggestion_endpoint path still works.
  • Additive. Provenance.mapped_from_predicate appears in MCP responses
    and every export format. NetworkX stores and .pkl snapshots 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-file holding exactly one change (add_pattern,
    map_to_existing or new_relation_type), --acl-ref and two output
    paths.
  • Authorization. It requires ontology_approver plus 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_granted is 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_BACKENDS lists the
    exact classes allowed to receive candidate evidence; subclasses and
    spoofed objects are still refused. Backends prove a local transport
    through a public attest_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 sealed ApprovedSuggestionBackend that 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_existing can 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.

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 as DROP TABLE x;.
    • map_to_existing and new_relation_type require a lower_snake_case
      observed_predicate and extractor_versions.
    • add_pattern rejects observed_predicate.
    • A new relation must keep the observed predicate.
  • Skipped evidence is reported. Candidates whose predicate isn't
    lower_snake_case (e.g. employedBy) are counted as skipped_count in the
    audit and the CLI, instead of being dropped silently. Ontology loading is
    unchanged.
  • CLI generation block. Shows mode, generator id and pinned version,
    invalid_count, skipped_count and the outcome audit query_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 a cancelled outcome record before re-raising. The trail no
    longer ends at request_started.
  • Pinned model version. generator_version is now model@sha256:<digest>,
    resolved once per run from the local Ollama /api/tags before any evidence
    is read. Outcome records also carry prompt_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=0 and an explicit num_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 as generator_id with generator_trust: "refused", so a trust
    refusal is distinguishable from a model failure.
  • invalid_count is 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 in Provenance.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_DIR and
    ONTOS_ONTOLOGY_HISTORY_DIR load 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 .pkl snapshots saved
    before mapped_from_predicate existed load correctly.

Fixed — verified migrations apply to every read surface (#112)

  • The gap. M3-1 hid facts without a verified migration path from ask
    and ontos query only. The MCP search, traverse, explain and
    provenance tools and ontos export still returned them.
  • Every read surface now projects through the same verified registry.
    • Excluded facts can't bridge traversals or --entity export
      neighbourhoods.
    • Exports drop untyped endpoints that only excluded facts name.
    • provenance answers null for an excluded fact.
    • search refetches to fill k.
  • Nothing reported back. Audit records name the ontology results were
    projected onto, and never what was excluded.
  • Exempt: the privileged --include-acl-mask export, which audits
    stored state.