bbs.profullstack/logicsrc
1
0
Fork 0
mirror of https://github.com/profullstack/logicsrc.git synced 2026-08-13 14:37:26 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Add the LogicSRC OpenContext specification (#132)

Browse source 
* 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:
Anthony Ettinger 2026-08-09 11:46:11 -07:00 • committed by GitHub
parent 1bb7ba6e60
commit 3ab8a4b38b
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
212 changed files with 17249 additions and 7 deletions
Download patch file Download diff file Expand all files Collapse all files

206
prd/0003-add-logicsrc-opencontext-spec.md Normal file
View file

@ -0,0 +1,206 @@
---
openprd: "0.2"
id: "0003"
title: "Add the LogicSRC OpenContext specification"
status: Draft
authors:
- anthony@profullstack.com
created: 2026-08-09
updated: 2026-08-09
repo: profullstack/logicsrc
discussion:
implementation:
tags:
- opencontext
- context
- agents
- permissions
- provenance
- schemas
supersedes:
superseded-by:
---
## Problem
Organizational context is fragmented across prompts, employee memory, agent
histories, vector stores, repositories, wikis, chats, issue trackers, CRMs,
spreadsheets, SOPs, databases, and proprietary memory systems.
The cost lands hardest when a worker is replaced. Swap an agent's model or
vendor and whatever it had learned goes with it; the organization re-teaches the
replacement from scratch. The same thing happens more slowly when a person
leaves.
The symptoms are specific and familiar: an agent confidently quoting last year's
pricing, two teams operating from two different refund policies with nobody able
to say which is authoritative, a support agent that can read the payroll file
because scope was never modelled, and a decision nobody can reconstruct because
the context it was made from is gone.
Underneath all of them is one missing thing: no portable, permissioned
description of **what the organization knows, which parts are authoritative, who
may read them, and how current they are**.
## Goals
- An agent can be replaced — different model, different vendor, different
framework — without the organization losing knowledge.
- Any two consumers of the same repository provably receive the context their
role entitles them to, and nothing else.
- A decision made by an agent can be reconstructed a year later, including which
context was and was not in front of it.
- Context rot is visible: stale, expired, conflicting, orphaned, and unowned
context is reported and can fail CI.
- The whole thing runs from a folder and a Git repository, with no hosted
account, no server, and no telemetry.
- A third-party implementation can conform using published schemas and fixtures
without reading LogicSRC source.
## Non-Goals
OpenContext does not replace vector databases, embeddings, RAG, MCP, IAM,
secrets managers, workflow engines, agent frameworks, LLM APIs, CRMs, ERPs,
wikis, ticket systems, document stores, or source control.
It is not a memory database. Memory is one possible context source; OpenContext
is the control plane above sources that remain the systems of record.
It does not authenticate callers. It enforces what a *named* consumer may read;
establishing who is asking belongs to the host application.
Semantic and vector retrieval are out of core conformance. They may be provided
by adapters or plugins, and must never be required to resolve context.
## Users
Primary: AI-agent developers, agent framework maintainers, AI-native companies,
engineering teams, platform engineers, operations teams, and developers running
more than one agent against shared knowledge.
Secondary: enterprises, consultants, security and compliance teams,
knowledge-management teams, DevOps and SRE teams, and individual agent-stack
developers.
## Requirements
- R1 [P0] Define `opencontext.yaml` and publish a JSON Schema for it.
- R2 [P0] Define a portable context object supporting inline and referenced
content, with `id` and `type` as the only required fields.
- R3 [P0] Define the six standard context layers, L0 mission through L5
operational.
- R4 [P0] Define six authority levels and deterministic conflict resolution,
with a total ordering so resolution is reproducible.
- R5 [P0] Detect duplicate canonical objects, multiple active versions, declared
conflicts, ambiguous equal-authority conflicts, and broken supersession, and
never hide an unresolved canonical conflict.
- R6 [P0] Define roles, scopes, classifications, object-level permissions, and
redaction, evaluated deny-overrides-allow with authorization strictly before
relevance.
- R7 [P0] Support freshness, validity windows, expiry, review cadence, and
durability, with lifecycle state computed against a timestamp rather than
stored.
- R8 [P0] Support versioning, declared supersession, and history, excluding
superseded objects from default resolution.
- R9 [P0] Resolve authorized task-specific context deterministically, and
produce a portable Context Bundle with a deterministic digest.
- R10 [P0] Preserve provenance through bundle compilation.
- R11 [P0] Preserve trust metadata, default remote content to untrusted, delimit
untrusted content in rendered bundles, and never elevate authority because
content claims it.
- R12 [P0] Ship a reference CLI with `init`, `validate`, `doctor`, `get`,
`list`, `search`, `resolve`, `history`, `diff`, `conflicts`, `stale`, `graph`,
`bundle`, `schema`, and `version`, with stable exit codes.
- R13 [P0] Ship a TypeScript SDK whose resolver core is importable without the
CLI.
- R14 [P0] Ship conformance fixtures and tests runnable by a third party, plus
resolution scenarios pinning behaviour schemas cannot express.
- R15 [P0] Reject path traversal, fail clearly on unknown URI schemes, never
execute context content, and fail validation on committed secrets.
- R16 [P0] Work offline with no mandatory network call and no hosted account.
- R17 [P1] Provide file, HTTP, Git, and SQLite adapters, and a documented
adapter contract for others.
- R18 [P1] Provide `doctor` with a documented, configurable health score that CI
can fail on by severity or minimum score.
- R19 [P1] Provide a decision object able to cite the Context Bundle it was made
from.
- R20 [P1] Support controlled writes that validate authorization and schema
before persistence, and prohibit automatic promotion of observed or inferred
context.
- R21 [P1] Provide a namespaced extension mechanism whose unknown values are
preserved and never invalidate an otherwise valid document.
- R22 [P1] Ship five working examples, all held to strict validation and a 100%
health score in CI.
- R23 [P1] Define an audit event shape without mandating a storage backend.
- R24 [P2] Publish performance benchmarks with budgets that gate a release.
- R25 [P2] Expose the specification through `logicsrc context` as well as a
standalone `opencontext` binary, sharing one implementation.
## UX Notes
`opencontext init` must produce a project that passes `validate --strict` and
scores 100% on `doctor` with no edits. A scaffold that emits warnings teaches
people in their first minute that warnings are normal, which is the habit this
specification exists to break. It generates two roles with genuinely different
scopes, so the permission model is visible immediately rather than in a doc.
Errors identify the file, line, object, field, expected value, actual value, and
a remediation. "Must match pattern" to someone who mistyped an id has
technically reported the problem and practically wasted their afternoon.
`--explain` shows why each object was included, excluded, or outranked, using a
closed set of exclusion reasons. Human output is the default; `--format json` is
the automation contract.
The standalone CLI and `logicsrc context` share one implementation, because the
specification treats CLI behaviour as a conformance surface and a subcommand
that quietly diverged would become a second contract.
## Success Metrics
- Time to first valid context under five minutes, with no account.
- 100% of shipped examples pass conformance in CI.
- Deterministic resolution: a repeated run over unchanged sources produces an
identical digest, asserted for every conformance scenario.
- Zero mandatory cloud dependencies and zero telemetry.
- 90%+ automated coverage of resolver and security-critical code.
- Every normative v1 behaviour represented by a conformance fixture.
- At least three documented third-party integration patterns at launch.
## Risks & Open Questions
- **Adoption friction.** A repository that demands full metadata on every object
will not get written. Mitigated by making `id` and `type` the only required
fields and treating a bare Markdown file as valid, so an existing `docs/`
folder is a starting point rather than a migration.
- **Score gaming.** A configurable health score can be tuned until it always
passes. Mitigated by publishing the formula and default weights so a tuned
configuration is visible in the manifest and reviewable.
- **Prompt injection beyond our reach.** OpenContext can label and delimit
untrusted content, but cannot force a downstream runtime to honour the
envelope. Documented as an integration requirement; an integration that
flattens the envelope loses the protection.
- **Digest churn.** A resolver bug fix that changes what is selected changes
bundle digests, which a consumer might read as tampering. Mitigated by calling
such fixes out explicitly in the changelog.
- **Blocker: the `opencontext` npm name is taken.** This PRD proposes
`opencontext` as the package name and `npx opencontext` as the install path.
That name is already published by an unrelated third party
(`federicodeponte/opencontext`, currently 2.0.0, "AI-powered company context
analysis from your terminal") — and being adjacent in subject matter makes the
confusion worse, not better. Documentation therefore ships pointing at
`npx @logicsrc/opencontext`, and the `bin` is still named `opencontext` so the
command reads as specified once installed. Resolving this needs a decision
before any publication: request a transfer, pick a different unscoped name, or
commit to the scoped package permanently.
- **No publication pipeline exists yet.** Neither `@logicsrc/openprd` nor
`@logicsrc/openontology` has ever been published to npm, so OpenContext is not
slotting into an established release path — one has to be built. Until then
the only distribution is this repository.
- **Open question.** Should interior wildcards (`customers.*.churn-risk`) remain
single-segment only, or should a future minor version add a bounded multi-
segment form? Single-segment is shipped in v1 because the alternative silently
widens access.
- **Open question.** Signed bundles, federated context, and a hosted registry
are all plausible post-v1. None is in the v1 commitment, and each risks
pulling a local-first specification toward a hosted default.

1
prd/README.md
View file

@ -13,3 +13,4 @@ Status lives in each file's front-matter and is the source of truth:
| --- | --- | --- | --- |
| [0001](./0001-add-logicsrc-openontology-spec.md) | Add the LogicSRC OpenOntology specification | Draft | openontology, ontology, knowledge-graph, agents, mcp, schemas |
| [0002](./0002-hourly-hire-us-rate.md) | Move Hire Us pricing from a weekly retainer to an hourly rate | Accepted | pricing, site, billing |
| [0003](./0003-add-logicsrc-opencontext-spec.md) | Add the LogicSRC OpenContext specification | Draft | opencontext, context, agents, permissions, provenance, schemas |