feat(openontology): implement OpenOntology Phase 0 + local engine and CLI (#99)
Some checks failed
CI / build (push) Has been cancelled
test / test (push) Has been cancelled

Implements OpenPRD 0001 through Phase 0 (specification, schemas, example,
docs surface) and Phase 1 (local engine, CLI, conformance tests).

Schemas (17 contracts, JSON Schema Draft 2020-12, additionalProperties:false)
  manifest, namespace, entity-type, property, relationship-type, constraint,
  query, action, entity, claim, source, evidence, changeset, review, approval,
  event, package — registered in @logicsrc/validators and exported from
  @logicsrc/schemas under https://logicsrc.com/schemas/openontology/.

@logicsrc/openontology
  - canonical JSON + sha256 package digests; YAML, JSON, NDJSON, and inline
    authoring all compile to the same bytes, so digests are authoring-agnostic
  - id profile: compact / IRI / urn with one canonicalization rule, prefix
    bound by a Namespace object so IRIs reverse unambiguously
  - validation: schema, graph (domain/range, datatypes, dangling refs),
    provenance (source-or-firstParty, agent runId, derivation inputs), policy
    (excerpt limits, licensing, visibility, staleness) and declared
    constraints; four severities, stable codes, text/json/yaml/markdown
  - portable triple-pattern query AST: multi-hop, 14 operators, asOf and
    recordedAsOf, per-status filtering, distinct/order/limit, explanation
    mode, and enforced depth/binding/row limits
  - append-only store: claims are immutable; dispute/retract/supersede append
    status transitions and the effective status is the latest one
  - change sets: 9 operations, atomic pre-flight, conflict detection on stale
    base revisions, semantic diff with duplicate-identity warnings and
    affected-query deltas, per-operation reviewer decisions
  - policy: agents propose but can never apply — the denial keys on actor
    type, so every scope plus high confidence plus --yolo still cannot apply;
    merges need approval, bulk retractions need two, undeclared action side
    effects are denied
  - JSON-LD 1.1 export/import with PROV-O aliases and lossy-field reporting
  - pluggable signature envelope with a jws-ed25519 reference profile and a
    fail-closed trust policy

CLI: logicsrc ontology init|validate|lint|build|inspect, entity, claim, query,
changeset, import, export, audit. Reads take --format, writes default to a
proposal, exit codes are stable for CI.

Example: examples/openontology/ethereum-ecosystem — 12 entity types, 17
relationship types, 63 entities, 169 claims, 25 sources, 31 evidence records,
5 saved queries, every claim lifecycle state, and a pending merge proposal.
All data is fictional; the directory is removable without affecting any core
test.

Docs: docs/openontology{,-governance,-interoperability}.md, a real
/openontology route, homepage + nav + sitemap entries, and a root README
section.

Verification: 112 new tests; full monorepo build and every workspace test
pass; conformance bundle (18 valid + 13 invalid fixtures) runs against the
published schemas alone; Node.js 25 and Bun 1.3 produce byte-identical
digests, revisions, event trails, and query results.

Not included (later PRD phases): MCP resources, REST/SSE, Turso adapter, TUI
and PWA surfaces, RDF/SHACL mappings, source adapters, governed actions.

Refs: prd/0001-add-logicsrc-openontology-spec.md

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Anthony Ettinger 2026-07-26 02:10:13 -07:00 committed by GitHub
parent 0d9dab0447
commit 58c942c67f
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
101 changed files with 11934 additions and 10 deletions

View file

@ -0,0 +1,158 @@
{
"openontologyConformance": "0.1",
"description": "Conformance fixtures for LogicSRC OpenOntology. A third-party implementation can run these against the published JSON Schemas with no LogicSRC code: every valid fixture must validate, every invalid fixture must fail.",
"valid": [
{
"fixture": "valid/manifest.json",
"kind": "openontology-manifest"
},
{
"fixture": "valid/namespace.json",
"kind": "openontology-namespace"
},
{
"fixture": "valid/entity-type.json",
"kind": "openontology-entity-type"
},
{
"fixture": "valid/property.json",
"kind": "openontology-property"
},
{
"fixture": "valid/relationship-type.json",
"kind": "openontology-relationship-type"
},
{
"fixture": "valid/constraint.json",
"kind": "openontology-constraint"
},
{
"fixture": "valid/query.json",
"kind": "openontology-query"
},
{
"fixture": "valid/query-adhoc.json",
"kind": "openontology-query"
},
{
"fixture": "valid/action.json",
"kind": "openontology-action"
},
{
"fixture": "valid/entity.json",
"kind": "openontology-entity"
},
{
"fixture": "valid/claim-relationship.json",
"kind": "openontology-claim"
},
{
"fixture": "valid/claim-value.json",
"kind": "openontology-claim"
},
{
"fixture": "valid/source.json",
"kind": "openontology-source"
},
{
"fixture": "valid/evidence.json",
"kind": "openontology-evidence"
},
{
"fixture": "valid/changeset.json",
"kind": "openontology-changeset"
},
{
"fixture": "valid/review.json",
"kind": "openontology-review"
},
{
"fixture": "valid/approval.json",
"kind": "openontology-approval"
},
{
"fixture": "valid/event.json",
"kind": "openontology-event"
}
],
"invalid": [
{
"fixture": "invalid/claim-both-objects.json",
"kind": "openontology-claim",
"mustFail": true,
"reason": "A claim object carries an entity reference or a typed value, never both."
},
{
"fixture": "invalid/claim-unknown-status.json",
"kind": "openontology-claim",
"mustFail": true,
"reason": "status must be one of the six declared claim states."
},
{
"fixture": "invalid/claim-confidence-out-of-range.json",
"kind": "openontology-claim",
"mustFail": true,
"reason": "confidence must be between 0 and 1."
},
{
"fixture": "invalid/claim-extra-property.json",
"kind": "openontology-claim",
"mustFail": true,
"reason": "Undeclared properties are rejected; extensions must go in the namespaced extensions object."
},
{
"fixture": "invalid/entity-missing-canonical-name.json",
"kind": "openontology-entity",
"mustFail": true,
"reason": "canonicalName is required on every entity."
},
{
"fixture": "invalid/manifest-no-maintainer.json",
"kind": "openontology-manifest",
"mustFail": true,
"reason": "At least one maintainer is required."
},
{
"fixture": "invalid/manifest-bad-version.json",
"kind": "openontology-manifest",
"mustFail": true,
"reason": "Package versions must be semantic versions."
},
{
"fixture": "invalid/manifest-bad-id.json",
"kind": "openontology-manifest",
"mustFail": true,
"reason": "Package ids are lowercase kebab-case."
},
{
"fixture": "invalid/relationship-no-range.json",
"kind": "openontology-relationship-type",
"mustFail": true,
"reason": "A relationship type must declare at least one allowed object type."
},
{
"fixture": "invalid/evidence-unknown-selector.json",
"kind": "openontology-evidence",
"mustFail": true,
"reason": "Evidence selectors must use one of the declared machine-readable shapes."
},
{
"fixture": "invalid/changeset-empty-operations.json",
"kind": "openontology-changeset",
"mustFail": true,
"reason": "A change set must contain at least one operation."
},
{
"fixture": "invalid/changeset-unknown-op.json",
"kind": "openontology-changeset",
"mustFail": true,
"reason": "Hard deletion is not an operation; use retract-claim or archive-entity."
},
{
"fixture": "invalid/action-no-permissions.json",
"kind": "openontology-action",
"mustFail": true,
"reason": "Actions must declare the scopes they require."
}
]
}

View file

@ -0,0 +1,13 @@
{
"openontology": "0.1",
"kind": "Action",
"id": "doThing",
"label": "Do thing",
"executor": {
"type": "http",
"endpoint": "https://example.org/do"
},
"approval": {
"mode": "none"
}
}

View file

@ -0,0 +1,10 @@
{
"openontology": "0.1",
"kind": "ChangeSet",
"id": "changeset:bad",
"title": "Nothing",
"createdAt": "2026-07-26T00:00:00Z",
"createdBy": "curator",
"operations": [],
"status": "proposed"
}

View file

@ -0,0 +1,15 @@
{
"openontology": "0.1",
"kind": "ChangeSet",
"id": "changeset:bad2",
"title": "Delete everything",
"createdAt": "2026-07-26T00:00:00Z",
"createdBy": "curator",
"operations": [
{
"op": "delete-claim",
"target": "ex:claim:0001"
}
],
"status": "proposed"
}

View file

@ -0,0 +1,14 @@
{
"openontology": "0.1",
"kind": "Claim",
"id": "ex:claim:bad",
"subject": "ex:person:alice",
"predicate": "worksOn",
"object": {
"entity": "ex:project:zk",
"value": "ZK"
},
"status": "asserted",
"assertedAt": "2026-07-26T00:00:00Z",
"assertedBy": "curator"
}

View file

@ -0,0 +1,14 @@
{
"openontology": "0.1",
"kind": "Claim",
"id": "ex:claim:bad3",
"subject": "ex:person:alice",
"predicate": "worksOn",
"object": {
"entity": "ex:project:zk"
},
"status": "asserted",
"confidence": 1.4,
"assertedAt": "2026-07-26T00:00:00Z",
"assertedBy": "curator"
}

View file

@ -0,0 +1,14 @@
{
"openontology": "0.1",
"kind": "Claim",
"id": "ex:claim:bad4",
"subject": "ex:person:alice",
"predicate": "worksOn",
"object": {
"entity": "ex:project:zk"
},
"status": "asserted",
"assertedAt": "2026-07-26T00:00:00Z",
"assertedBy": "curator",
"chainOfThought": "first I considered..."
}

View file

@ -0,0 +1,13 @@
{
"openontology": "0.1",
"kind": "Claim",
"id": "ex:claim:bad2",
"subject": "ex:person:alice",
"predicate": "worksOn",
"object": {
"entity": "ex:project:zk"
},
"status": "probably",
"assertedAt": "2026-07-26T00:00:00Z",
"assertedBy": "curator"
}

View file

@ -0,0 +1,8 @@
{
"openontology": "0.1",
"kind": "Entity",
"id": "ex:person:bob",
"type": "Person",
"createdAt": "2026-07-26T00:00:00Z",
"createdBy": "curator"
}

View file

@ -0,0 +1,10 @@
{
"openontology": "0.1",
"kind": "Evidence",
"id": "ex:evidence:bad",
"source": "ex:source:repo",
"selector": {
"type": "vibes",
"hint": "somewhere in the file"
}
}

View file

@ -0,0 +1,15 @@
{
"openontology": "0.1",
"kind": "OntologyPackage",
"id": "Example_Ontology",
"name": "Example",
"version": "0.1.0",
"namespace": "https://logicsrc.com/ontology/example/",
"description": "Id is not kebab-case.",
"license": "CC-BY-4.0",
"maintainers": [
{
"id": "mailto:c@example.org"
}
]
}

View file

@ -0,0 +1,15 @@
{
"openontology": "0.1",
"kind": "OntologyPackage",
"id": "example-ontology",
"name": "Example",
"version": "v1",
"namespace": "https://logicsrc.com/ontology/example/",
"description": "Version is not semver.",
"license": "CC-BY-4.0",
"maintainers": [
{
"id": "mailto:c@example.org"
}
]
}

View file

@ -0,0 +1,11 @@
{
"openontology": "0.1",
"kind": "OntologyPackage",
"id": "example-ontology",
"name": "Example",
"version": "0.1.0",
"namespace": "https://logicsrc.com/ontology/example/",
"description": "Missing maintainers.",
"license": "CC-BY-4.0",
"maintainers": []
}

View file

@ -0,0 +1,11 @@
{
"openontology": "0.1",
"kind": "RelationshipType",
"id": "worksOn",
"label": "works on",
"description": "Missing to.",
"from": [
"Person"
],
"to": []
}

View file

@ -0,0 +1,29 @@
{
"openontology": "0.1",
"kind": "Action",
"id": "createProjectReviewTask",
"label": "Create project review task",
"input": {
"project": {
"entityType": "Project",
"required": true
}
},
"executor": {
"type": "logicsrc-plugin-tool",
"plugin": "commandboard",
"tool": "task.create"
},
"permissions": {
"required": [
"ontology:action:execute"
]
},
"approval": {
"mode": "policy"
},
"sideEffects": [
"creates-task",
"emits-event"
]
}

View file

@ -0,0 +1,12 @@
{
"openontology": "0.1",
"kind": "Approval",
"id": "approval:0001",
"changeSet": "changeset:0001",
"approver": "mailto:curator@example.org",
"approverType": "human",
"scopes": [
"ontology:changeset:approve"
],
"createdAt": "2026-07-26T00:00:00Z"
}

View file

@ -0,0 +1,34 @@
{
"openontology": "0.1",
"kind": "ChangeSet",
"id": "changeset:0001",
"ontology": "example-ontology@0.1.0",
"title": "Add Alice as a contributor",
"rationale": "Repository activity identifies the contribution.",
"createdAt": "2026-07-26T00:00:00Z",
"createdBy": "agent:research-mapper",
"actorType": "agent",
"runId": "run_01J3EXAMPLE",
"operations": [
{
"op": "add-entity",
"value": {
"id": "ex:person:alice",
"type": "Person",
"canonicalName": "Alice Reyes"
}
},
{
"op": "assert-claim",
"value": {
"subject": "ex:person:alice",
"predicate": "worksOn",
"object": {
"entity": "ex:project:zk"
}
}
}
],
"requiredApprovals": 1,
"status": "proposed"
}

View file

@ -0,0 +1,23 @@
{
"openontology": "0.1",
"kind": "Claim",
"id": "ex:claim:0001",
"ontology": "example-ontology@0.1.0",
"subject": "ex:person:alice",
"predicate": "worksOn",
"object": {
"entity": "ex:project:zk"
},
"status": "asserted",
"confidence": 0.94,
"validTime": {
"from": "2026-04-01T00:00:00Z",
"to": null
},
"assertedAt": "2026-07-26T00:00:00Z",
"assertedBy": "agent:research-mapper",
"runId": "run_01J3EXAMPLE",
"sources": [
"ex:source:repo"
]
}

View file

@ -0,0 +1,15 @@
{
"openontology": "0.1",
"kind": "Claim",
"id": "ex:claim:0002",
"subject": "ex:project:zk",
"predicate": "homepage",
"object": {
"value": "https://example.org/zk",
"datatype": "url"
},
"status": "asserted",
"assertedAt": "2026-07-26T00:00:00Z",
"assertedBy": "mailto:curator@example.org",
"firstParty": true
}

View file

@ -0,0 +1,12 @@
{
"openontology": "0.1",
"kind": "Constraint",
"id": "project-has-homepage",
"description": "Projects should record a homepage.",
"severity": "warning",
"rule": {
"type": "required-predicate",
"entityType": "Project",
"predicate": "homepage"
}
}

View file

@ -0,0 +1,16 @@
{
"openontology": "0.1",
"kind": "EntityType",
"id": "Person",
"label": "Person",
"description": "A human participant.",
"keyProperties": [
"canonicalName"
],
"properties": {
"role": {
"type": "string",
"required": false
}
}
}

View file

@ -0,0 +1,16 @@
{
"openontology": "0.1",
"kind": "Entity",
"id": "ex:person:alice",
"type": "Person",
"canonicalName": "Alice Reyes",
"aliases": [
"alice.eth"
],
"externalIds": {
"github": "alice"
},
"status": "active",
"createdAt": "2026-07-26T00:00:00Z",
"createdBy": "mailto:curator@example.org"
}

View file

@ -0,0 +1,17 @@
{
"openontology": "0.1",
"kind": "Event",
"id": "event:0001",
"type": "changeset.applied",
"ontology": "example-ontology",
"at": "2026-07-26T00:00:00Z",
"actor": "mailto:curator@example.org",
"actorType": "human",
"changeSet": "changeset:0001",
"revision": "data-000042",
"policyDecision": {
"rule": "apply.scope",
"decision": "allow",
"reason": "Actor holds ontology:claim:write"
}
}

View file

@ -0,0 +1,12 @@
{
"openontology": "0.1",
"kind": "Evidence",
"id": "ex:evidence:0001",
"source": "ex:source:repo",
"selector": {
"type": "line-range",
"start": 41,
"end": 48
},
"excerpt": "Alice authored the prover module."
}

View file

@ -0,0 +1,21 @@
{
"openontology": "0.1",
"kind": "OntologyPackage",
"id": "example-ontology",
"name": "Example Ontology",
"version": "0.1.0",
"namespace": "https://logicsrc.com/ontology/example/",
"description": "A minimal conforming package manifest.",
"license": "CC-BY-4.0",
"maintainers": [
{
"id": "mailto:curator@example.org"
}
],
"schema": {
"entityTypes": "schema/entity-types.yaml"
},
"data": {
"entities": "data/entities.ndjson"
}
}

View file

@ -0,0 +1,7 @@
{
"openontology": "0.1",
"kind": "Namespace",
"prefix": "ex",
"uri": "https://logicsrc.com/ontology/example/",
"description": "Compact prefix for the example package."
}

View file

@ -0,0 +1,8 @@
{
"openontology": "0.1",
"kind": "Property",
"id": "homepage",
"label": "homepage",
"description": "Canonical URL.",
"type": "url"
}

View file

@ -0,0 +1,16 @@
{
"openontologyQuery": "0.1",
"ontology": "example-ontology@0.1.0",
"match": [
{
"subject": "?person",
"predicate": "worksOn",
"object": "ex:project:zk"
}
],
"select": [
"?person"
],
"asOf": "2026-07-26T00:00:00Z",
"limit": 100
}

View file

@ -0,0 +1,24 @@
{
"openontology": "0.1",
"kind": "SavedQuery",
"id": "contributors",
"description": "People working on a project.",
"query": {
"match": [
{
"subject": "?person",
"predicate": "worksOn",
"object": "?project"
}
],
"select": [
"?person",
"?project"
],
"include": {
"claimStatus": [
"asserted"
]
}
}
}

View file

@ -0,0 +1,16 @@
{
"openontology": "0.1",
"kind": "RelationshipType",
"id": "worksOn",
"label": "works on",
"description": "A person contributes work to a project.",
"from": [
"Person"
],
"to": [
"Project"
],
"cardinality": "many-to-many",
"temporal": true,
"inverse": "hasContributor"
}

View file

@ -0,0 +1,17 @@
{
"openontology": "0.1",
"kind": "Review",
"id": "review:0001",
"changeSet": "changeset:0001",
"reviewer": "mailto:curator@example.org",
"state": "changes-requested",
"comment": "Second operation lacks a source.",
"createdAt": "2026-07-26T00:00:00Z",
"operationDecisions": [
{
"index": 1,
"decision": "reject",
"comment": "no evidence"
}
]
}

View file

@ -0,0 +1,13 @@
{
"openontology": "0.1",
"kind": "Source",
"id": "ex:source:repo",
"sourceType": "git-commit",
"uri": "https://example.org/repo/commit/abc123",
"title": "Repository commit",
"publisher": "example.org",
"retrievedAt": "2026-07-26T00:00:00Z",
"contentHash": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"mediaType": "text/plain",
"license": "MIT"
}