@polydeukes/core 0.3.0

package/dist/transcript.js

@@ -0,0 +1,48 @@
+/**
+ * `CanonicalTranscript` — the agent-neutral session-query seam (CORE-04).
+ *
+ * Layering (PRD §1): this seam does not replace `CovenantInput`. The IR (CORE-01) is
+ * the *data* a covenant judges; `CanonicalTranscript` is the *behavioral seam* that
+ * queries session data — CORE-04 sits on top of CORE-01, and the IR is one source it
+ * can wrap. Concrete transcript formats stay in adapters; the core knows only the
+ * query vocabulary. Pure types and functions, zero I/O.
+ */
+/**
+ * The injection-absent default (PRD §4.2): every query answers "nothing happened".
+ * A witness consumer naturally converges to fail-closed — no evidence, no skip — and
+ * so does a precedent consumer (no evidence, gate stays shut).
+ */
+export const noopTranscript = {
+    findSubagentInvocations: () => [],
+    findUserMessages: () => [],
+    findToolCalls: () => [],
+};
+/**
+ * Wrap a {@link CovenantInput} as a {@link CanonicalTranscript} (PRD §4.2).
+ *
+ * Exposes `subagentSpawns` as invocations (filtered when a kind is given) and
+ * `userMessages` with `timestampMs` omitted — the bare IR cannot prove freshness,
+ * and that absence is the *correct* fail-closed signal for a witness consumer.
+ * Order preserved; the input is never mutated, and every query returns fresh
+ * objects so consumers never hold live aliases into the shared IR.
+ *
+ * `findToolCalls` projects each call down to `{ name, args }` only: since CORE-06 a
+ * call element also carries `fileChange` evidence, and evidence is judgment input, not
+ * session history — the two vocabularies stay separate (COVENANT-13 §4.2). `succeeded`
+ * stays absent for the same reason it is left three-valued: these calls are the ones
+ * being judged right now, so they have not run, and a call can never be its own
+ * precedent (COVENANT-13b §4.1).
+ */
+export function transcriptFromInput(input) {
+    return {
+        findSubagentInvocations: (kind) => input.subagentSpawns
+            .filter((spawn) => kind === undefined || spawn.kind === kind)
+            .map((spawn) => ({ kind: spawn.kind })),
+        findUserMessages: () => input.userMessages.map((message) => ({ text: message.text })),
+        findToolCalls: (name) => input.toolCalls
+            .filter((call) => name === undefined || call.name === name)
+            // Deep copy: args nest arbitrarily (real payloads are parsed JSON), and a shallow
+            // spread would leave nested values as live aliases into the IR the judges share.
+            .map((call) => ({ name: call.name, args: structuredClone(call.args ?? {}) })),
+    };
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@polydeukes/core",
+  "version": "0.3.0",
+  "description": "Polydeukes core — covenant protocol, config loader, and transcript interface. Domain- and agent-agnostic. Alpha.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/huskyhoochu/polydeukes.git",
+    "directory": "packages/core"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./schema.json": "./schema/polydeukes.schema.json"
+  },
+  "files": [
+    "dist",
+    "schema",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "ajv": "8.20.0",
+    "ajv-formats": "3.0.1",
+    "typescript": "7.0.2",
+    "vitest": "^4.1.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}

package/schema/polydeukes.schema.json

@@ -0,0 +1,200 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Polydeukes config",
+  "description": "Schema v2 (config as data) — equivalent to the runtime defineConfig() validator; the equivalence is enforced by a contract test.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["languages"],
+  "properties": {
+    "$schema": {
+      "description": "IDE schema reference — accepted and ignored by the runtime validator.",
+      "type": "string"
+    },
+    "languages": {
+      "description": "Language axis, first-class. Keys are user values ('typescript', 'python', ...).",
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": { "$ref": "#/$defs/languageProfile" }
+    },
+    "protectedPaths": {
+      "description": "Raw protected path patterns — normalization happens at resolve time.",
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "adapters": {
+      "description": "Adapter namespaces — keys are adapter names, values are each adapter's own settings object (contents not validated by the core schema).",
+      "type": "object",
+      "additionalProperties": { "type": "object" }
+    },
+    "telemetry": { "$ref": "#/$defs/telemetry" },
+    "disciplines": {
+      "description": "User-declared disciplines — validated data the covenant package compiles. Fully identical entries are copy-paste duplicates (by-id uniqueness is enforced by the runtime validator).",
+      "type": "array",
+      "uniqueItems": true,
+      "items": { "$ref": "#/$defs/discipline" }
+    },
+    "witness": { "$ref": "#/$defs/witness" }
+  },
+  "$defs": {
+    "languageProfile": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["productionGlob", "testCmd"],
+      "properties": {
+        "productionGlob": {
+          "description": "What counts as production source for this language.",
+          "anyOf": [
+            { "type": "string", "minLength": 1 },
+            {
+              "type": "array",
+              "minItems": 1,
+              "items": { "type": "string", "minLength": 1 }
+            }
+          ]
+        },
+        "testCmd": {
+          "description": "Shell command template that verifies the given scope — every literal {scope} token is substituted at resolve time.",
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "telemetry": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "logPath": {
+          "description": "Telemetry log path. Defaults to .polydeukes/roi.log when omitted.",
+          "type": "string"
+        }
+      }
+    },
+    "witness": {
+      "description": "TTL witness settings — the agreed token and validity window (minutes) consumed by the covenant valve assembly (CONFIG-05).",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["token", "ttlMinutes"],
+      "properties": {
+        "token": {
+          "description": "The agreed phrase a human types alone on a message's first line — quoting it mid-sentence is a mention, not an invocation (COVENANT-15). Must be non-empty after trimming; the value itself is free.",
+          "type": "string",
+          "minLength": 1,
+          "pattern": "\\S"
+        },
+        "ttlMinutes": {
+          "description": "Validity window in minutes from the user message's timestamp. Must be a finite number > 0.",
+          "type": "number",
+          "exclusiveMinimum": 0
+        }
+      }
+    },
+    "disciplineId": {
+      "description": "Unique handle — telemetry label and verdict reason prefix.",
+      "type": "string",
+      "minLength": 1
+    },
+    "disciplineWhy": {
+      "description": "Prose rationale, documentation only — never judged.",
+      "type": "string"
+    },
+    "globOrGlobs": {
+      "anyOf": [
+        { "type": "string", "minLength": 1 },
+        {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "minLength": 1 }
+        }
+      ]
+    },
+    "requirePrecedent": {
+      "description": "Context family — the session evidence one edit requires beforehand. Exactly one evidence key. The core owns and fully validates 'command'; every other key is adapter vocabulary whose value passes through verbatim (unconstrained here, judged by that adapter).",
+      "type": "object",
+      "minProperties": 1,
+      "maxProperties": 1,
+      "properties": {
+        "command": {
+          "description": "Core evidence vocabulary — regex over the shell command strings observed in the session.",
+          "type": "string",
+          "minLength": 1,
+          "format": "regex"
+        }
+      }
+    },
+    "discipline": {
+      "description": "One discipline entry — exactly one predicate family (forbid | immutable | forbidCommand | requirePrecedent); in/except scope the forbid and requirePrecedent families, and when scopes requirePrecedent only.",
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["id", "forbid"],
+          "properties": {
+            "id": { "$ref": "#/$defs/disciplineId" },
+            "why": { "$ref": "#/$defs/disciplineWhy" },
+            "in": { "$ref": "#/$defs/globOrGlobs" },
+            "except": { "$ref": "#/$defs/globOrGlobs" },
+            "forbid": {
+              "description": "Delta family — string shorthand is equivalent to { added }.",
+              "anyOf": [
+                { "type": "string", "format": "regex" },
+                {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["added"],
+                  "properties": {
+                    "added": { "type": "string", "format": "regex" }
+                  }
+                }
+              ]
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["id", "immutable"],
+          "properties": {
+            "id": { "$ref": "#/$defs/disciplineId" },
+            "why": { "$ref": "#/$defs/disciplineWhy" },
+            "immutable": {
+              "description": "Path family — its own glob is the scope.",
+              "$ref": "#/$defs/globOrGlobs"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["id", "forbidCommand"],
+          "properties": {
+            "id": { "$ref": "#/$defs/disciplineId" },
+            "why": { "$ref": "#/$defs/disciplineWhy" },
+            "forbidCommand": {
+              "description": "Command family — regex over shell command strings.",
+              "type": "string",
+              "format": "regex"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["id", "requirePrecedent"],
+          "properties": {
+            "id": { "$ref": "#/$defs/disciplineId" },
+            "why": { "$ref": "#/$defs/disciplineWhy" },
+            "in": { "$ref": "#/$defs/globOrGlobs" },
+            "except": { "$ref": "#/$defs/globOrGlobs" },
+            "when": {
+              "description": "Context-family trigger — added-direction delta regex. Absent means every in-scope change triggers.",
+              "type": "string",
+              "minLength": 1,
+              "format": "regex"
+            },
+            "requirePrecedent": { "$ref": "#/$defs/requirePrecedent" }
+          }
+        }
+      ]
+    }
+  }
+}