Skip to content

Releases

v0.10.0

Choose a tag to compare

@github-actions github-actions released this 17 Nov 18:12
1fea604

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 name ids. 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.
  • 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 :IngestedSource nodes 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
      before ontos reingest accepts them (#125).
  • ontos reingest needs deployment configuration:

    • ONTOS_AUDIT_DB_URL and an explicit ONTOS_AUDIT_SIGNING_KEY;
    • ONTOS_REINGEST_SOURCE_ROOT and ONTOS_REINGEST_OPERATOR_SUBJECT;
    • a loopback Ollama;
    • the operator must hold ontology_approver, plus VIEW on the source's
      ACL.

    See docs/scoped-reingest.md.

Added

  • ontos reingest re-extracts one registered source under its exact
    recorded ACL (#66 M3-3, #120).

    • Authorization comes first: ontology_approver and VIEW are checked
      before the store is opened or any file is read.
    • The command loads only the selected .txt, .md or .pdf, with
      O_NOFOLLOW and 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.
  • ONTOS_REINGEST_RECHECK_SECONDS (default 0, maximum 300) 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-sources lists the sources whose rejected
    evidence supports a signed migration record, split into those registered
    for ontos reingest and those not yet registered (#124). It requires
    ontology_approver, only considers evidence the operator may VIEW, and
    audits counts plus the same keyed scope reference ontos reingest records.

  • docs/scoped-reingest.md now 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.
  • Unchanged. Output stays deterministic and dependency-free, and keeps
    the same data-* metadata.

  • examples/demo/: a one-command local demo (run_demo.sh: ingest, ask,
    an MCP agent, audit verification, SVG graph) and a deterministic
    walkthrough of as_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 example Company: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.
  • 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.

v0.9.0

Choose a tag to compare

@github-actions github-actions released this 09 Nov 11:49
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.

v0.8.0

Choose a tag to compare

@github-actions github-actions released this 05 Nov 15:06
f217ae6

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=prod requires ONTOS_AUDIT_DB_URL. Without
    it, ontos serve refuses to boot. The Helm chart already sets it from
    the ontos-audit-db Secret.
  • 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 query and ontos ingest exit with code 1 before running if
      the audit store can't be opened.
  • Async database URLs only. Audit DB URLs must use an async driver:
    postgresql+asyncpg:// (install the new postgres extra; the image
    includes it) or sqlite+aiosqlite://. .env.example previously listed
    sync URLs that were always rejected.
  • Bounded arguments. MCP search k must be 1–100 and traverse
    depth 1–10. Values outside those ranges are rejected and audited.
  • Breaking for custom GraphStore implementations.
    • add_fact must reject an existing id (FactAlreadyExistsError).
    • close_fact must 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.
  • ask errors. ask is disabled until ONTOS_PLANNER_BACKEND=ollama
    and ONTOS_ONTOLOGY_PATH are 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 query still sees public facts only.

Performance — Neo4j traverse no longer enumerates every path (#104)

  • The problem. traverse matched (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 within depth - 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. DeterministicExecutor stamped every fact a traversal
    step returned with one hop. With TraversalStep(depth=3), a fact three
    hops from the seed scored like a direct neighbour, and hops_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 search applied LIMIT k to 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, then fact_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)

  • ask can now be enabled. Nothing ever built a planner for the server,
    so ask always answered "no planner configured". Set
    ONTOS_PLANNER_BACKEND=ollama with ONTOS_PLANNER_MODEL,
    ONTOS_PLANNER_URL, ONTOS_PLANNER_TIMEOUT and ONTOS_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_fact creates an untyped endpoint node for every id it
    references. scan(), which every ontos export format 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-mask export 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 query records the plan, the returned fact ids and the
      authorization decisions.
    • ontos ingest records 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 as operator_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_fact no longer rewrites a closed fact. Closing an already-closed
    fact used to move its t_invalid and replace superseded_by in both
    backends. It now raises FactNotOpenError. Closing a missing fact is still
    a no-op.
  • A duplicate add_fact is rejected in both backends with
    FactAlreadyExistsError. Before this, NetworkX replaced the fact in place
    and Neo4j created a second edge with the same fact_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), and ONTOS_ENV=prod refuses to boot.
  • Tool calls, transport rejections (401/403) and the audit tool 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 unavailable and returns no data. A transport rejection becomes a
    500. Sink error text is never returned or logged.
  • Records carry the real version. model_versions.runtime is now the
    package version, replacing the hard-coded 0.0.1.
  • New postgres extra (asyncpg), included in the container image.
    Before this the image could not connect to a Postgres audit DB.
    .env.example now 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
    malformed as_of, a malformed fact_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_error or error.
  • Callers get a safe message. Errors return a generic ToolError and never
    echo backend text; only the error type is logged (mcp-tool-failed).
  • **search k is bo...
Read more

v0.7.0

Choose a tag to compare

@github-actions github-actions released this 29 Oct 08:00
6a6ccc3

See CHANGELOG.md for details.

v0.6.0

Choose a tag to compare

@github-actions github-actions released this 12 Oct 17:36
a09f5c7

See CHANGELOG.md for details.

v0.5.0

Choose a tag to compare

@github-actions github-actions released this 07 Oct 08:01
ceaa9e0

See CHANGELOG.md for details.

v0.4.0

Choose a tag to compare

@github-actions github-actions released this 06 Oct 17:53
1865b7f

See CHANGELOG.md for details.

v0.3.0

Choose a tag to compare

@github-actions github-actions released this 06 Oct 05:11
a990896

See CHANGELOG.md for details.

v0.2.0

Choose a tag to compare

@github-actions github-actions released this 02 Oct 06:50
7774a02

See CHANGELOG.md for details.

v0.1.0

Choose a tag to compare

@github-actions github-actions released this 27 Sep 15:11
d5891ce

See CHANGELOG.md for details.