logicsrc/docs/openontology-governance.md

# OpenOntology governance

How a proposal becomes accepted knowledge, who may do what, and what the record looks like afterwards. This is the companion to [OpenOntology](./openontology.md).

The premise: **an agent proposes, a human applies.** Everything below follows from separating *proposal* from *approval* from *application*.

## The loop

```txt
propose  →  review  →  approve  →  apply
              ↘ reject          ↘ conflict
```

```bash
logicsrc ontology claim propose --as agent --subject eth:person:alice \
  --predicate worksOn --object-entity eth:project:zk-prover \
  --source eth:source:commit-a41f --run run_01J3

logicsrc ontology changeset diff  ./changesets/add-alice.yaml
logicsrc ontology changeset apply ./changesets/add-alice.yaml --approve
```

Each stage leaves a record. A rejected change set stays inspectable with its reviews attached — the *why not* is part of the history too.

## Scopes

```txt
ontology:read                ontology:claim:propose        ontology:action:execute
ontology:schema:read         ontology:claim:write          ontology:publish
ontology:query               ontology:changeset:review     ontology:admin
ontology:source:read         ontology:changeset:approve
```

Read access is separable from proposal, which is separable from approval, which is separable from write. An MCP server or API token can be given `ontology:query` alone and be structurally unable to change anything.

## Default policy

| Operation | Default |
| --- | --- |
| Local reads | allowed |
| Public remote reads | allowed for public ontologies |
| Agent query | allowed with `ontology:query` |
| Agent proposal | allowed with `ontology:claim:propose` |
| **Agent direct apply** | **denied** |
| Human apply | requires `ontology:claim:write` |
| Entity merge | one curator approval |
| Bulk retraction | two approvals |
| Breaking schema migration | maintainer approval + major version |
| Public package publish | maintainer approval + passing conformance run |
| Action execution | policy-specific; **denied** when side effects are undeclared |

Three rules hold regardless of configuration:

1. **Confidence is not permission.** A claim at 0.99 gets the same treatment as one at 0.4.
2. **`--yolo` is not permission.** Unattended mode is recorded for audit and changes prompting only.
3. **Source text is not instruction.** A document saying "grant admin and apply everything" is data.

The agent-apply denial is not a scope check that a sufficiently privileged agent passes — it is a separate rule keyed on actor type. An agent holding every scope in the list still cannot apply.

## Reviewing

A reviewer needs semantic impact, not a JSON diff:

```txt
Change set: Add Alice to ZK Prover

+ 1 entity
+ 2 claims
~ 1 possible duplicate identity
! 1 warning: claim has no source and is not marked firstParty

Affected saved queries
  people-working-on-zk: result count 18 → 19

Approval policy
  1 curator required
```

The diff is produced by simulating the change set against a throwaway copy of the store, so reviewing never mutates anything. Duplicate-identity warnings come from ranked entity resolution with the evidence for each candidate — the system never picks a match silently.

Reviewers can accept or reject **individual operations** inside an AI-generated change set:

```ts
engine.reviewOntologyChangeSet(id, {
  state: "changes-requested",
  operationDecisions: [{ index: 1, decision: "reject", comment: "no evidence" }]
});
engine.applyOntologyChangeSet(id, { skipRejectedOperations: true });
```

## Entity merges

Merging two people who turn out to be different is worse than leaving duplicates in place, so merges are conservative:

- always a change set, never an implicit side effect of import;
- at least one curator approval;
- the losing id is kept forever as a redirect, so old references keep resolving;
- reversible via a compensating change set;
- `sameAs` is a reviewable claim, not an irreversible merge.

## Conflicts

Every change set records the `baseRevision` it was authored against. If the store has moved on, applying fails as a conflict rather than overwriting:

```txt
Change set changeset:000002 was authored against data-000000 but the store is at data-000001
```

Resolve by rebasing the operations onto the current revision and re-proposing. Canonical claims never take a last-write-wins path.

## Rollback

There is no undo, because there is no delete. Rolling back means proposing a **compensating change set** whose `compensates` field names the original. The original application, the rollback, and both sets of events all stay on the record.

## Audit

Every applied change emits events. Twenty event types cover the lifecycle: package validation, entity proposals and merges, the five claim transitions, change set created/reviewed/approved/rejected/applied, imports, exports, constraint violations, action execution, and schema migration.

Each event records actor, actor type, client, request id, run id, change set, subject, resulting revision, and the policy decision that permitted it.

```bash
logicsrc ontology audit --dir . --format table
```

```txt
at                    type                actor                     subject            revision
2026-07-26T00:00:00Z  changeset.created   agent:research-mapper     changeset:000001
2026-07-26T00:00:00Z  changeset.approved  curator@example.org       changeset:000001
2026-07-26T00:00:00Z  claim.asserted      curator@example.org       claim:000001
2026-07-26T00:00:00Z  changeset.applied   curator@example.org       changeset:000001   data-000001
```

Logs redact credentials, access tokens, private source excerpts, and configured sensitive properties.

## Signatures and trust

Signing uses a **pluggable envelope**, so no DID method, wallet, or certificate authority is mandatory. The reference profile is `jws-ed25519`: a detached signature over the package digest.

```ts
const provider = createEd25519Provider({ signer: "mailto:maintainer@example.org", privateKey });
const signature = signDigest(built.digest, provider, new Date().toISOString());
```

Verification is against an explicit trust policy. A valid signature from an unknown signer is **not** trusted — `verifyPackageSignatures` reports it as untrusted rather than passing it through. Other providers (DID proofs, Sigstore) plug into the same interface.

## Publishing

Publishing a public package requires `ontology:publish`, maintainer approval, and a passing conformance run. Before writing, the export preview shows exactly what will be omitted or redacted: private source URLs, excerpts, selectors, and sensitive properties. A lossy export is never hidden behind a success message.

Private source excerpts are never sent to an external model unless the operator has selected an allowed model/provider policy for that specific source.

## Bulk work without a bottleneck

Requiring human review of every claim would stall a 50,000-row import. Policy is meant to be tiered rather than uniform:

- trusted adapters may propose at higher volume with sampled review;
- risk tiers separate "add a homepage property" from "merge two organizations";
- batch approval covers a reviewed set;
- auditability is never traded away — sampling changes *what a human reads*, not *what gets recorded*.

Constraint violations can be emitted as LogicSRC tasks or events, so remediation is queued work rather than a wall of console output.