Anthony Ettinger
3ab8a4b38b
* Add the LogicSRC OpenContext specification OpenContext is an open specification for durable, portable, permissioned, provenance-aware context shared between humans and AI agents. It defines how organizational knowledge is described, authorized, versioned, resolved, audited, and handed between replaceable workers without losing institutional state. Follows the OpenPRD/OpenOntology pattern already in the repo: self-contained JSON Schemas in @logicsrc/schemas, a reference implementation package, CLI subcommands, docs, examples, and an OpenPRD record. Schemas (8, all self-contained so a third party can fetch one file and validate against it with no further resolution): manifest, object, bundle, role, provenance, decision, diagnostic, audit-event — registered in @logicsrc/validators and schemas:validate. Reference implementation (@logicsrc/opencontext): loader with upward manifest discovery, the full resolution pipeline, authority/supersession, permissions, redaction, lifecycle, provenance, deterministic digests, doctor, search, graph, history/diff, guarded writes, audit events, and file/http/git/sqlite adapters. CLI: all 15 specified commands, as a standalone `opencontext` binary and as `logicsrc context`, sharing one implementation so the two cannot drift. Design decisions worth noting: - Supersession is declared, never inferred from version numbers. Inferring it would hide the governance failure it represents and make multiple-active-versions and duplicate-canonical impossible to detect. - The bundle digest identifies the resolved context, not the moment it was computed, so generated_at/bundle_id/digest/as_of are excluded while objects, lifecycle states, exclusions and warnings are covered. That is what lets a decision record cite exactly the context that produced it. - A role's own max_classification beats an inherited one, so a ceiling on a shared base role cannot silently cap a role deliberately granted more; requesting several roles at once still takes the lowest, so combining roles never escalates. - Scope wildcards match whole dotted segments only. A trailing .* covers a subtree; an interior * matches exactly one segment. Substring matching here would be an access-control bug. - --include narrows an existing scope and is applied after it, never merged into it, so a request can never widen what a role holds. Verified: 226 tests across core primitives, permissions/redaction, the resolution pipeline, security, the published conformance fixtures (13 valid, 35 invalid, 8 resolution scenarios), project behaviour, and the five shipped examples — which are held to --strict and a 100% health score. Benchmarks meet every published budget (resolve 1,000 objects in ~33ms against a 2s target). Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * Point install docs at @logicsrc/opencontext; record the npm name collision The unscoped `opencontext` name is already published on npm by an unrelated third party (federicodeponte/opencontext, 2.0.0), so `npx opencontext` would install a stranger's package. Docs now use `npx @logicsrc/opencontext`; the bin stays named `opencontext` so the command reads as the PRD specifies once installed. Recorded in PRD 0003 as a blocker to resolve before any publication, along with the fact that no @logicsrc spec package has ever been published, so there is no existing release path to slot into. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * Advance the logicsrc-mcp next-PRD-id assertion to 0004 standards.test.ts asserts prd_next_id against the live prd/ directory, so adding PRD 0003 makes the next free id 0004. The test's own comment anticipates this: "advances with every PRD added". Caught by CI, not locally — the earlier verification ran per-package tests for the packages this branch touches, and logicsrc-mcp is coupled to the PRD directory without importing from it. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
5.1 KiB
Versioning and migration policy
Three things are versioned
| Field | Example | |
|---|---|---|
| The specification | opencontext: in the manifest |
"1.0" |
| A context object | version: |
3 |
| The reference implementation | npm package version | 0.1.0 |
They move independently. A specification version is a contract; a package version is a release.
Specification versioning
Semantic versioning.
| Change | Bump | Example |
|---|---|---|
| New optional field, new diagnostic code, new adapter scheme | minor | adding summary |
| Clarification with no behavioural change | patch | tightening prose |
| New required field, removed field, changed default, changed resolution semantics | major | making owner required |
An implementation must refuse a major version it does not support rather than attempt a partial parse:
✗ Manifest declares OpenContext 2.0, but this implementation supports 1.0.
→ Set opencontext: "1.0", or use a runtime that implements 2.x.
A minor version is forward-compatible: a 1.0 runtime reading a 1.1 manifest ignores fields it does not know, and preserves unknown extensions.
Major breaking changes require a new major specification version. There is no silent semantic drift within a major line — if resolution would return different context for the same repository, that is a major change.
Extensions instead of forks
Before proposing a field, try an extension:
extensions:
com.example.risk:
score: 0.25
Namespaced keys never collide, survive resolution, land in the bundle, and do not invalidate a document in any conforming implementation. If an extension proves broadly useful, propose it for the next minor version.
--strict rejects extension keys that are not reverse-DNS namespaced, which is the only way an extension can fail validation.
Object versioning
version is monotonic within an id and is referenced as id@version.
Bump it when the meaning changes — a new refund window, a changed approval threshold. Do not bump it for a typo; edit in place and update updated.
Supersession is declared, never inferred from the number:
id: pricing.enterprise
version: 2
supersedes: [pricing.enterprise@1]
The previous version stays on disk. See lifecycle.
Renaming an id
An id is the contract other objects, roles, and bundles reference. Renaming is a breaking change.
Prefer supersession:
# context/policies/returns.md — the new id
id: policies.returns
supersedes: [policies.refunds]
The old object remains resolvable in historical queries, and history policies.returns still surfaces the chain. A hard rename silently breaks every references, every role include, and every archived bundle digest.
Migrating between minor versions
- Read the changelog.
- Bump
opencontext:in the manifest. - Run
opencontext validate --strict. - Run
opencontext doctor --strict. - Compare a bundle digest before and after — an unchanged digest proves resolution did not drift.
opencontext bundle --role support --output before.json
# bump the version
opencontext bundle --role support --output after.json
diff <(jq .digest before.json) <(jq .digest after.json)
That last step is the point of deterministic digests: a migration that changes what agents see is visible rather than assumed.
Deprecation
A field deprecated in a minor version keeps working for the remainder of the major line. Deprecations are announced in the changelog, surfaced as info diagnostics where a validator can detect them, and only removed in the next major version.
Implementation versioning
@logicsrc/opencontext follows semantic versioning independently. A patch may fix a resolver bug that changes output — if a bug caused an object to be wrongly included, fixing it changes bundles and digests. Such fixes are called out in the changelog, because a digest change is exactly what a consumer might otherwise treat as tampering.
Schema stability
Schemas are published at stable paths and shipped with releases:
https://logicsrc.com/schemas/opencontext/manifest.schema.json
https://logicsrc.com/schemas/opencontext/object.schema.json
https://logicsrc.com/schemas/opencontext/bundle.schema.json
https://logicsrc.com/schemas/opencontext/role.schema.json
https://logicsrc.com/schemas/opencontext/provenance.schema.json
https://logicsrc.com/schemas/opencontext/decision.schema.json
https://logicsrc.com/schemas/opencontext/diagnostic.schema.json
https://logicsrc.com/schemas/opencontext/audit-event.schema.json
Each is self-contained — no cross-file $ref — so a third-party implementation can fetch one file and validate against it with no further resolution. Diagnostic codes and bundle exclusion reasons are closed sets, and adding a value to either is a minor change.
Governance
Before v1.0 GA, the project defines specification maintainers, a public issue tracker, an RFC process, this versioning policy, a deprecation policy, a security disclosure process, a conformance policy, and an extension registration process.