@logicsrc/schemas 0.1.0

package/schemas/logicsrc-opencontext-provenance.schema.json

@@ -0,0 +1,76 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://logicsrc.com/schemas/opencontext/provenance.schema.json",
+  "title": "OpenContext Provenance Record",
+  "description": "Where one context object came from. Provenance answers 'who says so and when did we last check', which is a different question from 'is it true' (authority) and 'may you read it' (permissions). Provenance MUST survive bundle compilation: summarising or reformatting content may not erase its origin, because an agent that cannot cite its sources cannot be audited or corrected.",
+  "type": "object",
+  "required": ["id"],
+  "additionalProperties": false,
+  "anyOf": [
+    { "required": ["sources"], "properties": { "sources": { "type": "array" } } },
+    { "required": ["canonical_source"], "properties": { "canonical_source": { "const": true } } }
+  ],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9_-]*(\\.[a-z0-9][a-z0-9_-]*)*$",
+      "description": "The context object this record describes."
+    },
+    "canonical_source": {
+      "type": "boolean",
+      "description": "True when the object is itself the origin of the fact. A mission statement written in this repository has no upstream source and satisfies a provenance requirement on its own; a pricing object mirrored from a CRM does not."
+    },
+    "sources": {
+      "type": "array",
+      "minItems": 1,
+      "description": "Origins, most authoritative first. More than one source is normal — the same fact may be mirrored from a CRM and confirmed in a policy document.",
+      "items": { "$ref": "#/$defs/source" }
+    },
+    "retrieved_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "When the object as a whole was last refreshed from its sources, when that differs from the per-source timestamps."
+    },
+    "extensions": {
+      "type": "object",
+      "propertyNames": { "type": "string", "pattern": "^[a-z0-9]+(\\.[a-z0-9-]+)+$" },
+      "additionalProperties": true
+    }
+  },
+  "$defs": {
+    "source": {
+      "type": "object",
+      "required": ["uri"],
+      "additionalProperties": false,
+      "properties": {
+        "uri": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Where the content came from, e.g. git://github.com/acme/context/policies/refunds.md, crm://pricing/enterprise, or https://example.com/handbook. The scheme tells a reader which system to go argue with when the fact is wrong."
+        },
+        "type": {
+          "type": "string",
+          "description": "What kind of origin this is: canonical-record, document, conversation, observation, api, inference. An origin of type conversation or observation is a reason to keep the object's authority low."
+        },
+        "retrieved_at": { "type": "string", "format": "date-time", "description": "When these bytes were last read." },
+        "digest": {
+          "type": "string",
+          "pattern": "^(sha256):[0-9a-f]{64}$",
+          "description": "sha256:<64 lowercase hex> over the retrieved bytes. Lets a consumer detect that a remote source changed under them since the context was written, which is the difference between stale context and silently wrong context."
+        },
+        "label": { "type": "string", "description": "Human-readable name of the source." },
+        "trust": {
+          "type": "string",
+          "enum": ["trusted", "verified", "untrusted"],
+          "description": "Trust of this specific origin. A digest-checked external document is verified; a scraped page or a customer message is untrusted no matter how confident the object is."
+        },
+        "author": { "type": "string", "description": "Who produced the source material, when known." },
+        "extensions": {
+          "type": "object",
+          "propertyNames": { "type": "string", "pattern": "^[a-z0-9]+(\\.[a-z0-9-]+)+$" },
+          "additionalProperties": true
+        }
+      }
+    }
+  }
+}

package/schemas/logicsrc-opencontext-role.schema.json

@@ -0,0 +1,93 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://logicsrc.com/schemas/opencontext/role.schema.json",
+  "title": "OpenContext Role / Scope",
+  "description": "A named scope: the authorized subset of context available to a human, role, agent, task, or runtime. Roles answer 'may this consumer read it', which OpenContext keeps strictly separate from 'is it relevant'. Exclusions and denials are applied before relevance ranking, so unauthorized context never reaches a ranker, a prompt, or a bundle. This schema governs a single role; the manifest embeds the same shape under its roles map.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9_-]*$",
+      "description": "Role name. Optional when the role is embedded in a manifest, where the map key names it."
+    },
+    "description": {
+      "type": "string",
+      "description": "What this role is for, in one line."
+    },
+    "include": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": { "$ref": "#/$defs/pattern" },
+      "description": "Id patterns in scope, e.g. mission, products.*, policies.support.*. A role with no include list sees nothing: scope is opt-in, never opt-out."
+    },
+    "exclude": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": { "$ref": "#/$defs/pattern" },
+      "description": "Id patterns denied to this role. Deny overrides allow unconditionally — an exclusion cannot be outvoted by a more specific include, by inheritance, or by an object-level read grant."
+    },
+    "permissions": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": { "type": "string", "minLength": 1 },
+      "description": "Capability strings such as customer.read or ticket.write. OpenContext transports and scopes these so a runtime can enforce them; OpenContext does not itself perform your application's actions."
+    },
+    "max_classification": {
+      "$ref": "#/$defs/classification",
+      "description": "Highest classification this role may read. An object above the ceiling is denied even when an include pattern matches it. Defaults to internal, so confidential and restricted context requires an explicit grant."
+    },
+    "redact": {
+      "type": "array",
+      "description": "Redaction rules applied to everything this role reads, unioned with repository-wide and object-level rules.",
+      "items": { "$ref": "#/$defs/redaction" }
+    },
+    "inherits": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]*$" },
+      "description": "Roles whose scope merges into this one. Includes, excludes, and redactions all union, and the classification ceiling takes the lowest of the parents — inheritance can therefore only narrow what is readable, never widen it. Cycles are a validation error."
+    },
+    "extensions": { "$ref": "#/$defs/extensions" }
+  },
+  "$defs": {
+    "pattern": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^([a-z0-9][a-z0-9_-]*|\\*)(\\.([a-z0-9][a-z0-9_-]*|\\*))*$",
+      "description": "An exact object id (policy.refunds), a trailing wildcard covering a subtree (policies.support.*), an interior wildcard matching exactly one segment (customers.*.churn-risk), or * for everything. Wildcards always match whole dotted segments, never substrings, so products.* matches products.enterprise but never products-internal."
+    },
+    "classification": {
+      "type": "string",
+      "enum": ["public", "internal", "confidential", "restricted"],
+      "description": "Sensitivity band, least to most sensitive."
+    },
+    "redaction": {
+      "type": "object",
+      "required": ["path"],
+      "additionalProperties": false,
+      "description": "A rule removing or masking part of an object's structured content before it reaches a bundle.",
+      "properties": {
+        "path": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Dotted path into the object's content, with [] or [*] for every element of an array, e.g. customer.ssn or contacts[*].email."
+        },
+        "mode": {
+          "type": "string",
+          "enum": ["remove", "mask", "hash"],
+          "default": "remove",
+          "description": "remove deletes the key; mask replaces the value with the replacement string; hash replaces it with a sha256 digest so equality remains testable without disclosure."
+        },
+        "replacement": { "type": "string", "default": "[REDACTED]" },
+        "reason": { "type": "string", "description": "Why the field is redacted. Surfaced in --explain." }
+      }
+    },
+    "extensions": {
+      "type": "object",
+      "description": "Namespaced custom fields, e.g. com.example.risk.",
+      "propertyNames": { "type": "string", "pattern": "^[a-z0-9]+(\\.[a-z0-9-]+)+$" },
+      "additionalProperties": true
+    }
+  }
+}

package/schemas/logicsrc-openontology-action.schema.json

@@ -0,0 +1,90 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://logicsrc.com/schemas/openontology/action.schema.json",
+  "title": "LogicSRC OpenOntology Action",
+  "description": "A governed operation that turns a passive knowledge map into an operational layer. Actions reference approved LogicSRC plugin/tool capabilities; ontology packages never embed executable code.",
+  "type": "object",
+  "required": ["openontology", "kind", "id", "label", "executor", "permissions", "approval"],
+  "additionalProperties": false,
+  "properties": {
+    "openontology": { "type": "string", "pattern": "^\\d+\\.\\d+(\\.\\d+)?$" },
+    "kind": { "const": "Action" },
+    "id": { "type": "string", "minLength": 1 },
+    "label": { "type": "string", "minLength": 1 },
+    "description": { "type": "string" },
+    "input": {
+      "type": "object",
+      "additionalProperties": { "$ref": "#/$defs/parameter" }
+    },
+    "output": {
+      "type": "object",
+      "additionalProperties": { "$ref": "#/$defs/parameter" }
+    },
+    "preconditions": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "query": { "type": "string", "description": "Saved query id that must return rows." },
+        "constraints": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "executor": {
+      "type": "object",
+      "required": ["type"],
+      "additionalProperties": false,
+      "properties": {
+        "type": { "type": "string", "enum": ["logicsrc-plugin-tool", "mcp-tool", "http"] },
+        "plugin": { "type": "string" },
+        "tool": { "type": "string" },
+        "endpoint": { "type": "string" }
+      }
+    },
+    "permissions": {
+      "type": "object",
+      "required": ["required"],
+      "additionalProperties": false,
+      "properties": {
+        "required": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string" },
+          "uniqueItems": true
+        }
+      }
+    },
+    "approval": {
+      "type": "object",
+      "required": ["mode"],
+      "additionalProperties": false,
+      "properties": {
+        "mode": { "type": "string", "enum": ["none", "policy", "always"] },
+        "approvals": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "sideEffects": {
+      "type": "array",
+      "items": { "type": "string" },
+      "uniqueItems": true,
+      "description": "Declared effects. An undeclared side effect means the action is denied."
+    },
+    "idempotencyKey": {
+      "type": "string",
+      "description": "Input field used to make retries safe for non-idempotent effects."
+    },
+    "events": { "type": "array", "items": { "type": "string" }, "uniqueItems": true },
+    "extensions": { "type": "object" }
+  },
+  "$defs": {
+    "parameter": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "type": { "type": "string" },
+        "entityType": { "type": "string" },
+        "required": { "type": "boolean", "default": false },
+        "description": { "type": "string" },
+        "default": {}
+      }
+    }
+  }
+}

package/schemas/logicsrc-openontology-approval.schema.json

@@ -0,0 +1,39 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://logicsrc.com/schemas/openontology/approval.schema.json",
+  "title": "LogicSRC OpenOntology Approval",
+  "description": "A recorded approval that satisfies policy for a change set or governed action. Model confidence never substitutes for an approval.",
+  "type": "object",
+  "required": ["openontology", "kind", "id", "changeSet", "approver", "createdAt"],
+  "additionalProperties": false,
+  "properties": {
+    "openontology": { "type": "string", "pattern": "^\\d+\\.\\d+(\\.\\d+)?$" },
+    "kind": { "const": "Approval" },
+    "id": { "type": "string", "minLength": 1 },
+    "changeSet": { "type": "string", "minLength": 1 },
+    "approver": { "type": "string", "minLength": 1 },
+    "approverType": { "type": "string", "enum": ["human", "service", "agent"], "default": "human" },
+    "scopes": {
+      "type": "array",
+      "items": { "type": "string" },
+      "uniqueItems": true,
+      "description": "Scopes the approver held at approval time."
+    },
+    "policy": { "type": "string", "description": "Policy rule id that required this approval." },
+    "createdAt": { "type": "string", "format": "date-time" },
+    "comment": { "type": "string" },
+    "signature": {
+      "type": "object",
+      "required": ["algorithm", "signer", "value"],
+      "additionalProperties": false,
+      "properties": {
+        "algorithm": { "type": "string" },
+        "signer": { "type": "string" },
+        "value": { "type": "string" },
+        "created": { "type": "string", "format": "date-time" },
+        "keyId": { "type": "string" }
+      }
+    },
+    "extensions": { "type": "object" }
+  }
+}

package/schemas/logicsrc-openontology-changeset.schema.json

@@ -0,0 +1,168 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://logicsrc.com/schemas/openontology/changeset.schema.json",
+  "title": "LogicSRC OpenOntology Change Set",
+  "description": "An atomic, reviewable proposal to add, correct, merge, dispute, or retract knowledge. Agent-created change sets default to 'proposed'; rollback creates a compensating change set rather than deleting history.",
+  "type": "object",
+  "required": ["openontology", "kind", "id", "title", "createdAt", "createdBy", "operations", "status"],
+  "additionalProperties": false,
+  "properties": {
+    "openontology": { "type": "string", "pattern": "^\\d+\\.\\d+(\\.\\d+)?$" },
+    "kind": { "const": "ChangeSet" },
+    "id": { "type": "string", "minLength": 1 },
+    "ontology": { "type": "string", "description": "Target package reference, e.g. 'ethereum-ecosystem@0.1.0'." },
+    "title": { "type": "string", "minLength": 1 },
+    "rationale": { "type": "string" },
+    "createdAt": { "type": "string", "format": "date-time" },
+    "createdBy": { "type": "string", "minLength": 1 },
+    "actorType": { "type": "string", "enum": ["human", "service", "agent"] },
+    "runId": { "type": "string", "description": "REQUIRED for agent-created change sets." },
+    "operations": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/$defs/operation" }
+    },
+    "requiredApprovals": { "type": "integer", "minimum": 0, "default": 1 },
+    "status": {
+      "type": "string",
+      "enum": ["draft", "proposed", "approved", "applied", "rejected", "conflicted", "withdrawn"]
+    },
+    "baseRevision": {
+      "type": "string",
+      "description": "Data revision the change set was authored against. Used for optimistic concurrency."
+    },
+    "resultRevision": { "type": "string", "description": "Revision produced by applying the change set." },
+    "validation": { "$ref": "#/$defs/validationSummary" },
+    "appliedAt": { "type": "string", "format": "date-time" },
+    "appliedBy": { "type": "string" },
+    "compensates": { "type": "string", "description": "Change set id this one rolls back." },
+    "conflictsWith": { "type": "array", "items": { "type": "string" }, "uniqueItems": true },
+    "signatures": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["algorithm", "signer", "value"],
+        "additionalProperties": false,
+        "properties": {
+          "algorithm": { "type": "string" },
+          "signer": { "type": "string" },
+          "value": { "type": "string" },
+          "created": { "type": "string", "format": "date-time" },
+          "keyId": { "type": "string" }
+        }
+      }
+    },
+    "extensions": { "type": "object" }
+  },
+  "$defs": {
+    "validationSummary": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "ok": { "type": "boolean" },
+        "errors": { "type": "integer", "minimum": 0 },
+        "warnings": { "type": "integer", "minimum": 0 },
+        "info": { "type": "integer", "minimum": 0 },
+        "policy": { "type": "integer", "minimum": 0 },
+        "validatedAt": { "type": "string", "format": "date-time" }
+      }
+    },
+    "operation": {
+      "type": "object",
+      "required": ["op"],
+      "oneOf": [
+        {
+          "additionalProperties": false,
+          "required": ["op", "value"],
+          "properties": {
+            "op": { "const": "add-entity" },
+            "value": { "type": "object" },
+            "note": { "type": "string" }
+          }
+        },
+        {
+          "additionalProperties": false,
+          "required": ["op", "target", "value"],
+          "properties": {
+            "op": { "const": "update-metadata" },
+            "target": { "type": "string" },
+            "value": { "type": "object" },
+            "note": { "type": "string" }
+          }
+        },
+        {
+          "additionalProperties": false,
+          "required": ["op", "value"],
+          "properties": {
+            "op": { "const": "assert-claim" },
+            "value": { "type": "object" },
+            "note": { "type": "string" }
+          }
+        },
+        {
+          "additionalProperties": false,
+          "required": ["op", "target"],
+          "properties": {
+            "op": { "const": "dispute-claim" },
+            "target": { "type": "string" },
+            "reason": { "type": "string" },
+            "value": { "type": "object" },
+            "note": { "type": "string" }
+          }
+        },
+        {
+          "additionalProperties": false,
+          "required": ["op", "target"],
+          "properties": {
+            "op": { "const": "retract-claim" },
+            "target": { "type": "string" },
+            "reason": { "type": "string" },
+            "note": { "type": "string" }
+          }
+        },
+        {
+          "additionalProperties": false,
+          "required": ["op", "target", "value"],
+          "properties": {
+            "op": { "const": "supersede-claim" },
+            "target": { "type": "string" },
+            "value": { "type": "object" },
+            "reason": { "type": "string" },
+            "note": { "type": "string" }
+          }
+        },
+        {
+          "additionalProperties": false,
+          "required": ["op", "source", "target"],
+          "properties": {
+            "op": { "const": "merge-entity" },
+            "source": { "type": "string", "description": "Entity id being merged away; kept as a redirect." },
+            "target": { "type": "string", "description": "Surviving entity id." },
+            "reason": { "type": "string" },
+            "note": { "type": "string" }
+          }
+        },
+        {
+          "additionalProperties": false,
+          "required": ["op", "target"],
+          "properties": {
+            "op": { "const": "archive-entity" },
+            "target": { "type": "string" },
+            "reason": { "type": "string" },
+            "note": { "type": "string" }
+          }
+        },
+        {
+          "additionalProperties": false,
+          "required": ["op", "value"],
+          "properties": {
+            "op": { "const": "schema-migration" },
+            "value": { "type": "object" },
+            "breaking": { "type": "boolean", "default": false },
+            "note": { "type": "string" }
+          }
+        }
+      ]
+    }
+  }
+}

package/schemas/logicsrc-openontology-claim.schema.json

@@ -0,0 +1,148 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://logicsrc.com/schemas/openontology/claim.schema.json",
+  "title": "LogicSRC OpenOntology Claim",
+  "description": "The canonical fact record. A relationship is a claim whose object is an entity reference; a scalar property is a claim whose object is a typed value. Accepted claims are append-only — corrections are expressed as dispute, retraction, or supersession.",
+  "type": "object",
+  "required": ["openontology", "kind", "id", "subject", "predicate", "object", "status", "assertedAt", "assertedBy"],
+  "additionalProperties": false,
+  "properties": {
+    "openontology": { "type": "string", "pattern": "^\\d+\\.\\d+(\\.\\d+)?$" },
+    "kind": { "const": "Claim" },
+    "id": { "type": "string", "minLength": 1 },
+    "ontology": {
+      "type": "string",
+      "description": "Package reference the claim belongs to, e.g. 'ethereum-ecosystem@0.1.0'."
+    },
+    "subject": { "type": "string", "minLength": 1, "description": "Entity id." },
+    "predicate": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Relationship type id (entity object) or property id (value object)."
+    },
+    "object": { "$ref": "#/$defs/claimObject" },
+    "status": {
+      "type": "string",
+      "enum": ["asserted", "proposed", "disputed", "retracted", "superseded", "derived"]
+    },
+    "confidence": {
+      "type": "number",
+      "minimum": 0,
+      "maximum": 1,
+      "description": "Metadata about certainty. Confidence is never proof and never grants permission."
+    },
+    "validTime": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Domain valid time, independent of when the system recorded the claim.",
+      "properties": {
+        "from": { "type": ["string", "null"], "format": "date-time" },
+        "to": { "type": ["string", "null"], "format": "date-time" }
+      }
+    },
+    "observedAt": { "type": "string", "format": "date-time", "description": "Point-in-time observation." },
+    "assertedAt": { "type": "string", "format": "date-time", "description": "Recorded (system) time." },
+    "assertedBy": { "type": "string", "minLength": 1, "description": "Actor id — human, service, or agent." },
+    "runId": {
+      "type": "string",
+      "description": "LogicSRC-compatible run record. REQUIRED for agent-created claims."
+    },
+    "sources": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "uniqueItems": true
+    },
+    "evidence": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "uniqueItems": true
+    },
+    "firstParty": {
+      "type": "boolean",
+      "description": "Explicit declaration that this is a manual/first-party assertion with no external source."
+    },
+    "derivedFrom": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "REQUIRED for status 'derived': what produced this claim.",
+      "properties": {
+        "rule": { "type": "string" },
+        "query": { "type": "string" },
+        "transformation": { "type": "string" },
+        "inputs": { "type": "array", "items": { "type": "string" }, "uniqueItems": true }
+      }
+    },
+    "supersedes": { "type": "string", "description": "Claim id this claim replaces." },
+    "supersededBy": { "type": "string", "description": "Claim id that replaced this claim." },
+    "disputes": { "type": "string", "description": "Claim id this claim disputes." },
+    "retractionReason": { "type": "string" },
+    "changeSet": { "type": "string", "description": "Change set that introduced this claim." },
+    "license": { "type": "string" },
+    "visibility": {
+      "type": "string",
+      "enum": ["public", "internal", "private"],
+      "default": "public"
+    },
+    "retention": { "type": "string", "description": "Retention policy identifier." },
+    "tags": { "type": "array", "items": { "type": "string" }, "uniqueItems": true },
+    "model": { "$ref": "#/$defs/modelProvenance" },
+    "extensions": { "type": "object" }
+  },
+  "$defs": {
+    "claimObject": {
+      "description": "Exactly one of an entity reference or a typed scalar value — never both.",
+      "oneOf": [
+        {
+          "type": "object",
+          "required": ["entity"],
+          "additionalProperties": false,
+          "properties": {
+            "entity": { "type": "string", "minLength": 1 }
+          }
+        },
+        {
+          "type": "object",
+          "required": ["value"],
+          "additionalProperties": false,
+          "properties": {
+            "value": {},
+            "datatype": {
+              "type": "string",
+              "enum": [
+                "string",
+                "number",
+                "integer",
+                "boolean",
+                "date",
+                "date-time",
+                "duration",
+                "url",
+                "email",
+                "enum",
+                "object",
+                "array",
+                "binary-reference"
+              ]
+            },
+            "language": { "type": "string", "pattern": "^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$" },
+            "unit": { "type": "string" }
+          }
+        }
+      ]
+    },
+    "modelProvenance": {
+      "type": "object",
+      "required": ["provider", "model"],
+      "additionalProperties": false,
+      "description": "Recorded for AI-extracted proposals. Never stores chain-of-thought.",
+      "properties": {
+        "provider": { "type": "string", "minLength": 1 },
+        "model": { "type": "string", "minLength": 1 },
+        "modelVersion": { "type": "string" },
+        "promptVersion": { "type": "string" },
+        "extractedAt": { "type": "string", "format": "date-time" },
+        "rationale": { "type": "string", "description": "Concise user-facing rationale only." }
+      }
+    }
+  }
+}