mirror of
https://github.com/profullstack/logicsrc.git
synced 2026-10-02 04:43:58 +00:00
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>
210 lines
9.9 KiB
JSON
210 lines
9.9 KiB
JSON
{
|
|
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
"$id": "https://logicsrc.com/schemas/opencontext/bundle.schema.json",
|
|
"title": "OpenContext Context Bundle",
|
|
"description": "The portable output of resolution: the authorized, valid, current subset of context selected for one consumer and one task, with its provenance and a deterministic digest. JSON is the canonical interchange form. A bundle is the unit that makes agents replaceable — the same bundle handed to a different model or runtime carries the same organizational knowledge, and a decision can record exactly which context produced it by citing the digest.",
|
|
"type": "object",
|
|
"required": ["opencontext", "bundle_id", "generated_at", "consumer", "objects", "digest"],
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"opencontext": {
|
|
"type": "string",
|
|
"pattern": "^\\d+\\.\\d+(\\.\\d+)?$",
|
|
"description": "Specification version the bundle conforms to."
|
|
},
|
|
"bundle_id": {
|
|
"type": "string",
|
|
"pattern": "^ocb_[a-z0-9_-]+$",
|
|
"description": "Identifier for this bundle, prefixed ocb_. Derived from the digest by the reference implementation so identical inputs produce an identical id."
|
|
},
|
|
"generated_at": {
|
|
"type": "string",
|
|
"format": "date-time",
|
|
"description": "When the bundle was compiled. Excluded from the digest so that two runs over unchanged sources are byte-identical apart from this field."
|
|
},
|
|
"namespace": {
|
|
"type": "string",
|
|
"pattern": "^[a-z0-9][a-z0-9-]*$",
|
|
"description": "The manifest id the bundle was resolved from."
|
|
},
|
|
"consumer": {
|
|
"type": "object",
|
|
"required": ["type", "id"],
|
|
"additionalProperties": false,
|
|
"description": "Who this bundle was resolved for. Recorded so an audit can answer which agent saw which context.",
|
|
"properties": {
|
|
"type": { "type": "string", "enum": ["agent", "human", "role", "service"] },
|
|
"id": { "type": "string", "minLength": 1 },
|
|
"roles": {
|
|
"type": "array",
|
|
"uniqueItems": true,
|
|
"items": { "type": "string", "minLength": 1 },
|
|
"description": "Effective roles applied during authorization."
|
|
}
|
|
}
|
|
},
|
|
"task": {
|
|
"type": "string",
|
|
"description": "The task the context was resolved for, verbatim. Used for relevance ranking and recorded for reproducibility."
|
|
},
|
|
"as_of": {
|
|
"type": "string",
|
|
"format": "date-time",
|
|
"description": "The instant resolution was evaluated against. Lifecycle state, supersession, and validity windows are all judged at this timestamp, so passing --at reproduces a past view of context."
|
|
},
|
|
"objects": {
|
|
"type": "array",
|
|
"description": "The resolved context, in deterministic order: layer, then authority, then id. Content here has already been authorized, filtered, and redacted.",
|
|
"items": { "$ref": "#/$defs/bundledObject" }
|
|
},
|
|
"excluded": {
|
|
"type": "array",
|
|
"description": "What was considered and left out, and why. Populated when --explain is requested; a bundle with an empty excluded list is not a claim that nothing was excluded.",
|
|
"items": { "$ref": "#/$defs/exclusion" }
|
|
},
|
|
"warnings": {
|
|
"type": "array",
|
|
"description": "Non-fatal findings that survived into the bundle: stale context, unresolved canonical conflicts, missing provenance, untrusted content. Warnings are never silently dropped.",
|
|
"items": { "$ref": "#/$defs/warning" }
|
|
},
|
|
"provenance": {
|
|
"type": "array",
|
|
"description": "Flattened source records for every object in the bundle. Provenance MUST survive compilation, so this list stands on its own even if content was summarised.",
|
|
"items": { "$ref": "#/$defs/provenanceEntry" }
|
|
},
|
|
"permissions": {
|
|
"type": "array",
|
|
"uniqueItems": true,
|
|
"items": { "type": "string", "minLength": 1 },
|
|
"description": "Capability strings the consumer holds, carried through for the runtime to enforce."
|
|
},
|
|
"stats": {
|
|
"type": "object",
|
|
"additionalProperties": false,
|
|
"description": "Counters describing the resolution, useful for context budgeting.",
|
|
"properties": {
|
|
"considered": { "type": "integer", "minimum": 0 },
|
|
"included": { "type": "integer", "minimum": 0 },
|
|
"excluded": { "type": "integer", "minimum": 0 },
|
|
"redacted": { "type": "integer", "minimum": 0 },
|
|
"characters": { "type": "integer", "minimum": 0, "description": "Total characters of compiled content. A proxy for token cost that needs no tokenizer." }
|
|
}
|
|
},
|
|
"digest": {
|
|
"type": "string",
|
|
"pattern": "^sha256:[0-9a-f]{64}$",
|
|
"description": "sha256 over the canonical JSON of the bundle with generated_at and digest themselves omitted. Deterministic: identical source state and inputs produce an identical digest, which is what lets a decision record cite exactly the context that produced it."
|
|
},
|
|
"extensions": { "$ref": "#/$defs/extensions" }
|
|
},
|
|
"$defs": {
|
|
"bundledObject": {
|
|
"type": "object",
|
|
"required": ["id", "type"],
|
|
"additionalProperties": true,
|
|
"description": "A resolved context object. Carries the object's declared fields plus the state the resolver computed for it.",
|
|
"properties": {
|
|
"id": { "type": "string", "minLength": 1 },
|
|
"type": { "type": "string", "minLength": 1 },
|
|
"layer": { "type": "string", "enum": ["L0", "L1", "L2", "L3", "L4", "L5"] },
|
|
"title": { "type": "string" },
|
|
"content": { "anyOf": [{ "type": "string" }, { "type": "object" }, { "type": "array" }] },
|
|
"content_type": { "type": "string" },
|
|
"authority": { "type": "string", "enum": ["canonical", "approved", "reference", "observed", "inferred", "historical"] },
|
|
"trust": {
|
|
"type": "string",
|
|
"enum": ["trusted", "verified", "untrusted"],
|
|
"description": "Preserved through resolution. An integration MUST be able to tell canonical policy apart from text a stranger wrote into a ticket."
|
|
},
|
|
"owner": { "type": "string" },
|
|
"version": { "type": "integer", "minimum": 1 },
|
|
"updated": { "type": "string", "format": "date-time" },
|
|
"classification": { "type": "string", "enum": ["public", "internal", "confidential", "restricted"] },
|
|
"durability": { "type": "string", "enum": ["ephemeral", "session", "operational", "long-lived", "permanent"] },
|
|
"lifecycle": {
|
|
"type": "string",
|
|
"enum": ["future", "current", "stale", "expired", "superseded"],
|
|
"description": "Computed against as_of, not stored on the object."
|
|
},
|
|
"redacted": {
|
|
"type": "array",
|
|
"items": { "type": "string" },
|
|
"description": "Paths removed or masked before compilation. The bundle discloses that redaction happened without disclosing what was redacted."
|
|
},
|
|
"sources": { "type": "array", "items": { "type": "object" } },
|
|
"tags": { "type": "array", "items": { "type": "string" } },
|
|
"extensions": { "$ref": "#/$defs/extensions" }
|
|
}
|
|
},
|
|
"exclusion": {
|
|
"type": "object",
|
|
"required": ["id", "reason"],
|
|
"additionalProperties": false,
|
|
"description": "One object that was considered and rejected, with the pipeline stage that rejected it.",
|
|
"properties": {
|
|
"id": { "type": "string", "minLength": 1 },
|
|
"reason": {
|
|
"type": "string",
|
|
"enum": [
|
|
"permission-denied",
|
|
"classification-denied",
|
|
"scope-exclusion",
|
|
"not-in-scope",
|
|
"superseded",
|
|
"expired",
|
|
"not-yet-valid",
|
|
"outranked",
|
|
"unapproved",
|
|
"not-relevant",
|
|
"conflict",
|
|
"source-unavailable"
|
|
],
|
|
"description": "Why it was left out. permission-denied and classification-denied are authorization outcomes and are decided before any relevance work is done."
|
|
},
|
|
"detail": { "type": "string", "description": "Human-readable specifics, e.g. the pattern that excluded it or the object that outranked it." },
|
|
"outranked_by": { "type": "string", "description": "Id of the object that won, when reason is outranked or superseded." }
|
|
}
|
|
},
|
|
"warning": {
|
|
"type": "object",
|
|
"required": ["code", "message"],
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"code": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
|
|
"message": { "type": "string", "minLength": 1 },
|
|
"id": { "type": "string", "description": "Object the warning concerns, when it concerns one." },
|
|
"severity": { "type": "string", "enum": ["info", "warning", "error"], "default": "warning" }
|
|
}
|
|
},
|
|
"provenanceEntry": {
|
|
"type": "object",
|
|
"required": ["id"],
|
|
"additionalProperties": false,
|
|
"description": "Where one bundled object came from.",
|
|
"properties": {
|
|
"id": { "type": "string", "minLength": 1, "description": "The context object id." },
|
|
"canonical_source": { "type": "boolean", "description": "True when the object is itself the origin and has no upstream source." },
|
|
"sources": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "object",
|
|
"required": ["uri"],
|
|
"additionalProperties": true,
|
|
"properties": {
|
|
"uri": { "type": "string", "minLength": 1 },
|
|
"type": { "type": "string" },
|
|
"retrieved_at": { "type": "string", "format": "date-time" },
|
|
"digest": { "type": "string", "pattern": "^(sha256):[0-9a-f]{64}$" },
|
|
"trust": { "type": "string", "enum": ["trusted", "verified", "untrusted"] }
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"extensions": {
|
|
"type": "object",
|
|
"propertyNames": { "type": "string", "pattern": "^[a-z0-9]+(\\.[a-z0-9-]+)+$" },
|
|
"additionalProperties": true
|
|
}
|
|
}
|
|
}
|