mirror of
https://github.com/profullstack/logicsrc.git
synced 2026-08-13 14:37:26 +00:00
Add the LogicSRC OpenContext specification (#132)
* 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>
This commit is contained in:
GitHub
parent
1bb7ba6e60
commit
3ab8a4b38b
212 changed files with 17249 additions and 7 deletions
79
docs/opencontext/related-specs.md
Normal file
79
docs/opencontext/related-specs.md
Normal file
|
|
@ -0,0 +1,79 @@
|
|||
# OpenPRD and OpenTopology integration
|
||||
|
||||
| Specification | Primary question |
|
||||
| --- | --- |
|
||||
| [OpenPRD](../openprd.md) | What are we building and why? |
|
||||
| OpenTopology | How is the system organized? |
|
||||
| [OpenContext](../opencontext.md) | What does everyone need to know? |
|
||||
|
||||
```txt
|
||||
OpenPRD -> intent / requirements
|
||||
OpenTopology -> architecture / relationships
|
||||
OpenContext -> knowledge / policy / operational context
|
||||
LogicSRC -> execution by humans and agents
|
||||
```
|
||||
|
||||
**OpenContext must remain independently usable.** These integrations are optional, and nothing in resolution depends on them.
|
||||
|
||||
## Linking
|
||||
|
||||
```yaml
|
||||
opencontext: "1.0"
|
||||
id: acme
|
||||
|
||||
related:
|
||||
prd: ./openprd.yaml
|
||||
topology: ./opentopology.yaml
|
||||
ontology: ./openontology.yaml
|
||||
```
|
||||
|
||||
## Referencing by stable id
|
||||
|
||||
Once linked, context objects can cite requirements and components by their stable ids:
|
||||
|
||||
```yaml
|
||||
id: decisions.2026-08-09-postgres-ha
|
||||
type: decision
|
||||
title: Move Core to replicated Postgres
|
||||
decision: Run Core on a primary with a synchronous replica.
|
||||
extensions:
|
||||
com.logicsrc.openprd:
|
||||
requirements: ["0004-R3"]
|
||||
com.logicsrc.opentopology:
|
||||
components: [core, ledger]
|
||||
```
|
||||
|
||||
Cross-specification references use the extension mechanism rather than first-class fields, which keeps them genuinely optional: a runtime that knows nothing about OpenPRD preserves the extension and resolves the object normally.
|
||||
|
||||
## Where each belongs
|
||||
|
||||
The boundary that matters in practice:
|
||||
|
||||
| Question | Lives in |
|
||||
| --- | --- |
|
||||
| Why are we building this? | OpenPRD |
|
||||
| What are the requirements? | OpenPRD |
|
||||
| Which services exist and how do they talk? | OpenTopology |
|
||||
| What does this component own? | OpenTopology |
|
||||
| What is our refund policy? | OpenContext |
|
||||
| How does support process a refund? | OpenContext |
|
||||
| Why did we choose this database? | OpenContext (a decision record) |
|
||||
| What is the current incident state? | OpenContext (L5 operational) |
|
||||
|
||||
A useful test: **would this still matter after the feature shipped?** If yes, it is context. If it describes the work rather than the organization, it is a PRD.
|
||||
|
||||
## Complementary, not overlapping
|
||||
|
||||
OpenPRD documents are numbered proposals with a lifecycle (`Draft → Review → Accepted → Final`). OpenContext objects are durable knowledge with authority, scope, and supersession. A PRD can *become* context — an accepted decision inside a PRD is worth extracting into a decision record, so agents receive it without reading the whole proposal.
|
||||
|
||||
OpenOntology models entities and source-backed claims. Where OpenContext says "this is our refund policy and support may read it", OpenOntology says "Avery works on the ZK Prover, and here is the commit that says so". A repository can use both: OpenContext for governed prose and policy, OpenOntology for structured facts.
|
||||
|
||||
## Using them together
|
||||
|
||||
```bash
|
||||
logicsrc prd list # what we are building
|
||||
logicsrc context list --role eng # what an engineer needs to know
|
||||
logicsrc ontology query run … # structured facts
|
||||
```
|
||||
|
||||
All three are local-first, schema-first, and usable without a hosted account — and each is independently adoptable. Start with whichever answers the question that is currently costing you.
|
||||
Loading…
Add table
Add a link
Reference in a new issue