logicsrc/packages/openontology/src/index.ts
Anthony Ettinger da5f6f8381
Some checks are pending
CI / build (push) Waiting to run
test / test (push) Waiting to run
feat(openontology): Phase 2 + Phase 3 — storage, REST/SSE, MCP, RDF/SHACL, adapters, TUI, explorer (#101)
Everything the two shipped PRD phases deferred, minus what is called out below.

Storage (Phase 2)
  @logicsrc/openontology gains a SQLite/Turso adapter. It hydrates the read
  model at open, serves reads synchronously — a query evaluator that awaits per
  triple pattern is unusable — and buffers mutations as SQL that flush() writes
  in one transaction. Versioned idempotent migrations; indexes over subject,
  predicate, entity-valued object, status, both time axes, aliases, and external
  ids; FTS5 for label/alias search. The append-only status log is replayed on
  open, so retractions, supersessions, and merge redirects survive a reopen.

REST + SSE + OpenAPI (Phase 2)
  16 paths under /api/ontologies in logicsrc-web, described at
  /api/ontologies/openapi and referencing the published JSON Schemas rather
  than restating them. No token is read-only; a curator token can apply; an
  agent token can propose and cannot apply. Idempotency-Key on mutations,
  revision ETags, 409 on a stale base revision, and an SSE stream that emits
  the same event objects as the JSON endpoint.

MCP (Phase 2)
  OpenOntology and OpenPRD surfaces on the standards server: spec/manifest/
  schema/queries and PRD spec/index as resources, 11 ontology tools and 6 PRD
  tools, 7 prompts. Read-only by default; OPENONTOLOGY_MCP_WRITABLE=1 buys
  proposals, never applies — the denial is the shared policy layer, not a
  second rule that could drift.

Interoperability (Phase 3)
  RDF/Turtle export and import of the reified profile, plus the plain triple
  for asserted relationships so a consumer wanting only the accepted graph gets
  one. SHACL for 5 of 7 constraint kinds; `unique` and `query` are reported as
  unmapped in both the return value and the generated Turtle, because a shape
  that quietly means something narrower is worse than no shape.

Source adapters (Phase 3)
  CSV, JSON, YAML, NDJSON, Markdown, generic JSON HTTP, and GitHub. All produce
  PROPOSED change-set operations with source, evidence selector, run id, and
  confidence attached; fetch is injected so ingestion is offline and testable.
  Each declares its capabilities, so "nothing was deleted upstream" is never
  confused with "this adapter cannot see deletions" — none of the seven can.

TUI + explorer
  Keyboard-first panels (types, entities, claims, sources, queries, change
  sets, validation, audit) as plain strings that survive SSH and 60 columns;
  status is a glyph and a word, never colour alone; the key bar wraps rather
  than truncating. Wired as `logicsrc ontology tui`. A read-only web explorer
  at /openontology/explore with entity and claim views showing status, both
  clocks, confidence, sources, evidence, and append-only history — plus an
  /openprd page for the companion standard.

Bugs found and fixed while testing
  - the API built a new engine per request, so `explain` could never find a
    resultId from a prior request; engines are now cached per role
  - the TUI status bar called engine.validateOntologyPackage(), appending a
    package.validated event on every repaint; it now uses the pure validator

Verification: 76 new tests (527 total across the monorepo, all passing); full
build green; the libSQL adapter is exercised against real files, the API
through its route handlers, and MCP over an in-memory transport.

Not included: PWA review/approval write flows (they need an auth story this
deployment does not have), OWL/RDFS mappings, SPARQL/Cypher/Datalog query
adapters, and Phase 4 governed actions. The compatibility matrix marks those
"planned", not "supported".

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

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-07-28 05:10:33 -07:00

150 lines
2.9 KiB
TypeScript

/**
* @logicsrc/openontology — reference implementation of the LogicSRC
* OpenOntology standard.
*
* This package IMPLEMENTS the standard; it does not define it. The normative
* contracts are the JSON Schemas published in @logicsrc/schemas under
* https://logicsrc.com/schemas/openontology/. Any implementation that
* satisfies those schemas and the conformance suite conforms, whether or not
* it uses a single line of this code.
*/
export { OPENONTOLOGY_VERSION } from "./types.js";
export type * from "./types.js";
export { canonicalize, canonicalObject, digest, packageDigest } from "./canonical.js";
export {
createIdFactory,
idForm,
idPrefix,
isValidId,
isVariable,
revisionId,
toIri,
type IdForm
} from "./ids.js";
export {
buildOntologyPackage,
loadOntologyPackage,
verifyPackageDigest,
PackageLoadError,
SCHEMA_SECTIONS,
DATA_SECTIONS,
type LoadInput
} from "./package.js";
export {
renderReport,
validateOntologyPackage,
type ReportFormat,
type ValidateOptions
} from "./validate.js";
export {
DEFAULT_LIMITS,
evaluateQuery,
validAt,
QueryLimitError,
type KnowledgeView,
type QueryLimits
} from "./query.js";
export {
createLibsqlStore,
migrate as migrateLibsql,
searchEntities,
MIGRATIONS,
type LibsqlStore,
type LibsqlStoreOptions
} from "./libsql.js";
export {
createMemoryStore,
type ClaimFilter,
type EntityFilter,
type EntityMatch,
type OntologyStore,
type StatusTransition
} from "./store.js";
export {
evaluatePolicy,
localActor,
proposerActor,
readOnlyActor,
SCOPES,
type Actor,
type Operation,
type PolicyDecision,
type PolicyOptions,
type Scope
} from "./policy.js";
export {
applyChangeSet,
diffChangeSet,
ChangeSetApplyError,
ChangeSetConflictError,
type ApplyContext,
type ApplyResult,
type SemanticDiff
} from "./changeset.js";
export {
buildContext,
exportJsonLd,
importJsonLd,
packagePrefix,
OO,
PROV,
type JsonLdExport
} from "./jsonld.js";
export {
ADAPTERS,
csvAdapter,
githubAdapter,
httpApiAdapter,
jsonAdapter,
listAdapters,
markdownAdapter,
ndjsonAdapter,
parseCsv,
yamlAdapter,
type AdapterCapabilities,
type AdapterId,
type FetchLike,
type IngestContext,
type IngestResult,
type RecordMapping,
type SourceAdapter
} from "./adapters.js";
export { exportTurtle, importTurtle, type TurtleExport } from "./rdf.js";
export { constraintsToShacl, type ShaclExport } from "./shacl.js";
export {
createEd25519Provider,
generateEd25519KeyPair,
signDigest,
verifyDigestSignature,
verifyPackageSignatures,
type SignatureProvider,
type VerificationResult
} from "./signature.js";
export {
createOntologyEngine,
OntologyApprovalError,
OntologyNotFoundError,
OntologyPermissionError,
type EngineOptions,
type Explanation,
type ExplainedClaim,
type OntologyEngine
} from "./engine.js";
export { initOntologyPackage, type InitOptions, type InitResult } from "./scaffold.js";