@polydeukes/core 0.6.1 → 0.8.0

package/README.ko.md

@@ -47,4 +47,4 @@ const payload = parseInput('{"toolCalls":[],"subagentSpawns":[],"userMessages":[
 
 - [`@polydeukes/core` 패키지 레퍼런스](../../docs/reference/packages/core.ko.md)
 - [`설정 레퍼런스`](../../docs/reference/configuration/index.ko.md)
-- [`@polydeukes/covenant`](../../docs/reference/packages/covenant.ko.md)
+- [판정기(`covenant` 모듈)](../../docs/reference/packages/polydeukes.ko.md#covenant-module)

package/README.md

@@ -47,4 +47,4 @@ const payload = parseInput('{"toolCalls":[],"subagentSpawns":[],"userMessages":[
 
 - [`@polydeukes/core` package reference](../../docs/reference/packages/core.md)
 - [`Configuration reference`](../../docs/reference/configuration/index.md)
-- [`@polydeukes/covenant`](../../docs/reference/packages/covenant.md)
+- [The judge (`covenant` module)](../../docs/reference/packages/polydeukes.md#covenant-module)

package/dist/algebra.d.ts

@@ -172,3 +172,12 @@ export type Witnesses = readonly Witness[];
  * `location`, so a caller validating many declarations sees which one failed.
  */
 export declare function validateAlgebraDeclaration(input: unknown, location?: string): AlgebraDeclaration;
+/**
+ * `DeclarationChannel` — one evidence channel a declaration binds.
+ *
+ * `transcript` · `channel` · `command` · `actor` are what a live call carries and `changes`
+ * is what a finished change set carries, so the set a declaration reads decides which
+ * surfaces can observe it at all.
+ */
+export type DeclarationChannel = 'transcript' | 'channel' | 'command' | 'actor' | 'changes';
+export declare function declarationChannels(body: Omit<AlgebraDeclaration, 'discipline'>): DeclarationChannel[];

package/dist/algebra.js

@@ -5,7 +5,7 @@
  * The module knows no judgment. It runs no extraction and evaluates no relation; the
  * kernel expansion laws quoted on each relation branch below are comments, never code.
  */
-import { validateMechanism } from './catalogue.js';
+import { sourceNames, validateMechanism } from './catalogue.js';
 import { isPlainObject } from './is-plain-object.js';
 import { FIXED_SOURCE_NAMES } from './source-names.js';
 import { ConfigValidationError, isNonEmptyString, isStringArray, rejectUncompilableRegex, rejectUnknownKeys, } from './validation.js';
@@ -436,3 +436,34 @@ export function validateAlgebraDeclaration(input, location = 'declaration') {
     validateMechanism(declaration, location);
     return declaration;
 }
+/** The fixed order of a derived channel list. */
+const DECLARATION_CHANNELS = [
+    'transcript',
+    'channel',
+    'command',
+    'actor',
+    'changes',
+];
+export function declarationChannels(body) {
+    const found = new Set();
+    const sources = isPlainObject(body.sources) ? body.sources : {};
+    for (const binding of Object.values(sources)) {
+        if (!isPlainObject(binding))
+            continue;
+        if ('transcript' in binding)
+            found.add('transcript');
+        if ('sidecar' in binding)
+            found.add('channel');
+    }
+    if (isPlainObject(body.scope) && body.scope.source === 'command')
+        found.add('command');
+    for (const name of sourceNames(body)) {
+        if (name === 'command')
+            found.add('command');
+        if (name === 'actor')
+            found.add('actor');
+        if (name === 'changes')
+            found.add('changes');
+    }
+    return DECLARATION_CHANNELS.filter((channel) => found.has(channel));
+}

package/dist/catalogue.d.ts

@@ -45,6 +45,13 @@ export type DerivedShape = {
 };
 /** Every name's spec. The `Record` type pins the keys to {@link MECHANISM_NAMES}. */
 export declare const MECHANISM_SHAPES: Record<MechanismName, MechanismShape>;
+/** Every source name the body and the valve read, in declaration order. */
+export declare function sourceNames(declaration: {
+    extract?: unknown;
+    witness?: {
+        extract?: unknown;
+    } | undefined;
+}): string[];
 /**
  * Read one declaration's shape from its syntax (pure).
  *

package/dist/catalogue.js

@@ -101,12 +101,19 @@ function quotedList(names) {
 function isTranscriptSource(binding) {
     return isPlainObject(binding) && binding.transcript === true;
 }
-/** The source names one extract block's `source` steps name, in declaration order. */
+/**
+ * The source names one extract block's `source` steps name, in declaration order.
+ *
+ * Tolerant of an unvalidated block: a pipeline that is not a list, or a step that is not an
+ * object, names nothing here and is refused by the grammar validator with its location.
+ */
 function sourceNamesOf(extract) {
-    if (extract === undefined)
+    if (!isPlainObject(extract))
         return [];
     const names = [];
     for (const steps of Object.values(extract)) {
+        if (!Array.isArray(steps))
+            continue;
         for (const step of steps) {
             if (isPlainObject(step) && step.op === 'source' && typeof step.of === 'string') {
                 names.push(step.of);
@@ -116,8 +123,9 @@ function sourceNamesOf(extract) {
     return names;
 }
 /** Every source name the body and the valve read, in declaration order. */
-function sourceNames(declaration) {
-    return [...sourceNamesOf(declaration.extract), ...sourceNamesOf(declaration.witness?.extract)];
+export function sourceNames(declaration) {
+    const witness = isPlainObject(declaration.witness) ? declaration.witness : undefined;
+    return [...sourceNamesOf(declaration.extract), ...sourceNamesOf(witness?.extract)];
 }
 /**
  * Read one declaration's shape from its syntax (pure).

package/dist/config.d.ts

@@ -95,8 +95,18 @@ export type PolydeukesConfig = {
         /** conventional default applies when omitted */
         logPath?: string;
     };
-    /** user-declared disciplines — validated here, compiled by the covenant package */
+    /**
+     * user-declared disciplines both surfaces observe — every entry whose declaration binds
+     * no evidence channel, plus the drafts. Validated here, compiled by the covenant package
+     */
     disciplines?: (DisciplineEntry | DisciplineDraft)[];
+    /**
+     * disciplines only the session surface observes — every entry binding at least one of
+     * `transcript` · `channel` · `command` · `actor` and never `changes`
+     */
+    sessionDisciplines?: DisciplineEntry[];
+    /** disciplines only the change-set surface observes — every entry binding `changes` */
+    changeSetDisciplines?: DisciplineEntry[];
     /**
      * TTL witness values for the covenant valve seam — consumed at assembly time,
      * validated here
@@ -141,6 +151,10 @@ export type ResolvedConfig = {
      * declared a `disciplines` array, holding exactly its judged entries in order.
      */
     disciplines?: DisciplineEntry[];
+    /** validated session-surface entries, present whenever the input declared the list */
+    sessionDisciplines?: DisciplineEntry[];
+    /** validated change-set-surface entries, present whenever the input declared the list */
+    changeSetDisciplines?: DisciplineEntry[];
     /** validated drafts in declaration order (absent when the input carries none) */
     drafts?: DisciplineDraft[];
     /** validated witness data, passed through verbatim (absent stays absent) */

package/dist/config.js

@@ -6,7 +6,7 @@
  * saw. It stays a pure function — no file I/O and no runtime dependencies: validation is
  * hand-rolled, and the published JSON Schema is a sibling artifact this source never reads.
  */
-import { validateAlgebraDeclaration } from './algebra.js';
+import { declarationChannels, validateAlgebraDeclaration, } from './algebra.js';
 import { isPlainObject } from './is-plain-object.js';
 import { ConfigValidationError, isNonEmptyString, isStringArray, rejectUnknownKeys, } from './validation.js';
 export { ConfigValidationError } from './validation.js';
@@ -21,6 +21,8 @@ const TOP_LEVEL_KEYS = new Set([
     'adapters',
     'telemetry',
     'disciplines',
+    'sessionDisciplines',
+    'changeSetDisciplines',
     'witness',
 ]);
 const PROFILE_KEYS = new Set(['productionGlob', 'testCmd']);
@@ -94,26 +96,66 @@ function validateDeclareEntry(entry, location) {
     }
     validateAlgebraDeclaration({ discipline: entry.id, ...block }, `${location} declare`);
 }
+/** The three list names an entry can be written in — also the destinations of a misplacement. */
+const DISCIPLINE_LISTS = ['disciplines', 'sessionDisciplines', 'changeSetDisciplines'];
+/** The channels only a live call carries; `changes` is the one only a change set carries. */
+const SESSION_CHANNELS = [
+    'transcript',
+    'channel',
+    'command',
+    'actor',
+];
 /**
- * Validate the `disciplines` array and split judged entries from drafts. Throws
+ * The list an entry's declaration belongs in, from the channels it binds — or `undefined`
+ * when it binds both a session channel and `changes`, which no surface observes at once.
+ */
+function listFor(channels) {
+    const readsSession = channels.some((channel) => SESSION_CHANNELS.includes(channel));
+    const readsChanges = channels.includes('changes');
+    if (readsSession && readsChanges)
+        return undefined;
+    if (readsSession)
+        return 'sessionDisciplines';
+    if (readsChanges)
+        return 'changeSetDisciplines';
+    return 'disciplines';
+}
+/**
+ * Refuse a judged entry written in a list the surface it needs does not read. The channels
+ * its declaration binds are the whole answer, so the message names them and the destination:
+ * an author who is told only that the placement is wrong meets the same error again.
+ */
+function checkPlacement(entry, list, location) {
+    const channels = declarationChannels(entry.declare);
+    const destination = listFor(channels);
+    if (destination === undefined) {
+        throw new ConfigValidationError(`${location} reads ${channels.join(', ')}: no surface observes both changes and a session channel`);
+    }
+    if (destination !== list) {
+        const reads = channels.length === 0 ? 'no evidence channel' : channels.join(', ');
+        throw new ConfigValidationError(`${location} reads ${reads}: it belongs in ${destination}`);
+    }
+}
+/**
+ * Validate one discipline list and split judged entries from drafts. Throws
  * {@link ConfigValidationError} naming the offending entry/key; the validated data passes
- * through verbatim, in declaration order.
+ * through verbatim, in declaration order. `seenIds` spans the three lists and the meta
+ * labels, so a label the telemetry space already carries is refused wherever it is written.
  */
-function validateDisciplines(disciplines) {
+function validateDisciplines(disciplines, list, seenIds) {
     if (!Array.isArray(disciplines)) {
-        throw new ConfigValidationError('disciplines must be an array');
+        throw new ConfigValidationError(`${list} must be an array`);
     }
     const judged = [];
     const drafts = [];
-    const seenIds = new Set();
     disciplines.forEach((entry, index) => {
         if (!isPlainObject(entry)) {
-            throw new ConfigValidationError(`disciplines[${index}] must be an object`);
+            throw new ConfigValidationError(`${list}[${index}] must be an object`);
         }
         if (typeof entry.id !== 'string' || entry.id.length === 0) {
-            throw new ConfigValidationError(`disciplines[${index}].id must be a non-empty string`);
+            throw new ConfigValidationError(`${list}[${index}].id must be a non-empty string`);
         }
-        const location = `disciplines[${index}] ('${entry.id}')`;
+        const location = `${list}[${index}] ('${entry.id}')`;
         if (seenIds.has(entry.id)) {
             throw new ConfigValidationError(`${location} duplicates the id of an earlier entry`);
         }
@@ -127,10 +169,20 @@ function validateDisciplines(disciplines) {
         // Selected by the marker's value, so an explicit `draft: undefined` is absence,
         // like every other optional key in this validator.
         if (entry.draft !== undefined) {
+            // A draft carries no declaration, so it binds no channel and there is nothing for a
+            // surface list to observe.
+            if (list !== 'disciplines') {
+                throw new ConfigValidationError(`${location} a draft belongs in disciplines`);
+            }
             drafts.push(validateDraft(entry, entry.id, location));
             return;
         }
         validateEntryHead(entry, location);
+        // Placement first: the derivation is syntactic, so an entry in the wrong list is told
+        // where it belongs rather than meeting a grammar error the move would not fix.
+        if (isPlainObject(entry.declare)) {
+            checkPlacement(entry, list, location);
+        }
         validateDeclareEntry(entry, location);
         judged.push(entry);
     });
@@ -250,7 +302,18 @@ export function defineConfig(config) {
     const resolvedLanguages = validateLanguages(config.languages);
     const protectedPaths = config.protectedPaths !== undefined ? validateProtectedPaths(config.protectedPaths) : undefined;
     const adapters = config.adapters !== undefined ? validateAdapters(config.adapters) : undefined;
-    const split = config.disciplines !== undefined ? validateDisciplines(config.disciplines) : undefined;
+    // One id space across the three lists and the meta labels: `explain` and every
+    // label-keyed telemetry reader index by the label alone.
+    const seenIds = new Set();
+    const split = config.disciplines !== undefined
+        ? validateDisciplines(config.disciplines, 'disciplines', seenIds)
+        : undefined;
+    const sessionDisciplines = config.sessionDisciplines !== undefined
+        ? validateDisciplines(config.sessionDisciplines, 'sessionDisciplines', seenIds).judged
+        : undefined;
+    const changeSetDisciplines = config.changeSetDisciplines !== undefined
+        ? validateDisciplines(config.changeSetDisciplines, 'changeSetDisciplines', seenIds).judged
+        : undefined;
     const disciplines = split?.judged;
     const drafts = split !== undefined && split.drafts.length > 0 ? split.drafts : undefined;
     const logPath = config.telemetry !== undefined ? validateTelemetry(config.telemetry) : undefined;
@@ -263,6 +326,8 @@ export function defineConfig(config) {
             logPath: logPath ?? DEFAULT_TELEMETRY_LOG_PATH,
         },
         ...(disciplines !== undefined && { disciplines }),
+        ...(sessionDisciplines !== undefined && { sessionDisciplines }),
+        ...(changeSetDisciplines !== undefined && { changeSetDisciplines }),
         ...(drafts !== undefined && { drafts }),
         ...(witness !== undefined && { witness }),
     };

package/dist/index.d.ts

@@ -6,7 +6,7 @@
  * (appendRecord / readRecords / appendRecordFailOpen).
  * See https://github.com/huskyhoochu/polydeukes
  */
-export { type AlgebraDeclaration, BINARY_COMBINATOR_NAMES, type BinaryStep, type ExtractBlock, type ExtractStep, RELATION_NAMES, type RelateEntry, type RelationDecl, type RelationName, type ScopeBlock, SUPPLY_POLICIES, type SupplyBlock, type UnaryStep, validateAlgebraDeclaration, type Witness, type WitnessBlock, type Witnesses, } from './algebra.ts';
+export { type AlgebraDeclaration, BINARY_COMBINATOR_NAMES, type BinaryStep, type DeclarationChannel, declarationChannels, type ExtractBlock, type ExtractStep, RELATION_NAMES, type RelateEntry, type RelationDecl, type RelationName, type ScopeBlock, SUPPLY_POLICIES, type SupplyBlock, type UnaryStep, validateAlgebraDeclaration, type Witness, type WitnessBlock, type Witnesses, } from './algebra.ts';
 export { AXIS_NAMES, type Axis, type DerivableDeclaration, deriveShape, MECHANISM_NAMES, MECHANISM_SHAPES, type MechanismName, type MechanismShape, } from './catalogue.ts';
 export { type AlgebraDeclarationBody, ConfigValidationError, DEFAULT_TELEMETRY_LOG_PATH, type DisciplineDraft, type DisciplineEntry, defineConfig, type EnforceLevel, type LanguageProfile, type PolydeukesConfig, type ResolvedConfig, type ResolvedLanguageProfile, } from './config.ts';
 export { EXIT_BREAK_BLOCKING, EXIT_BREAK_NON_BLOCKING, EXIT_UPHOLD, } from './exit-codes.ts';
@@ -15,4 +15,4 @@ export { isPlainObject } from './is-plain-object.ts';
 export { normalizeProtectedPaths } from './protected-paths.ts';
 export { allFileChanges, type ChannelReader, type CovenantInput, type CovenantVerdict, type DispatchOutcome, type FileChange, parseInput, type SourceReader, verdictToExitCode, } from './protocol.ts';
 export { aggregateGain, appendRecord, appendRecordFailOpen, formatRecordLine, type GainSummary, parseRecordLine, readRecords, runGain, SKIP_REASONS, type SkipReason, type TelemetryEvent, type TelemetryRecord, } from './telemetry.ts';
-export { type CanonicalTranscript, noopTranscript, type TranscriptToolCall, type TranscriptUserMessage, transcriptFromInput, } from './transcript.ts';
+export { type CanonicalTranscript, noopTranscript, type TranscriptToolCall, type TranscriptUserMessage, transcriptFromInput, transcriptFromSession, } from './transcript.ts';

package/dist/index.js

@@ -6,7 +6,7 @@
  * (appendRecord / readRecords / appendRecordFailOpen).
  * See https://github.com/huskyhoochu/polydeukes
  */
-export { BINARY_COMBINATOR_NAMES, RELATION_NAMES, SUPPLY_POLICIES, validateAlgebraDeclaration, } from './algebra.js';
+export { BINARY_COMBINATOR_NAMES, declarationChannels, RELATION_NAMES, SUPPLY_POLICIES, validateAlgebraDeclaration, } from './algebra.js';
 export { AXIS_NAMES, deriveShape, MECHANISM_NAMES, MECHANISM_SHAPES, } from './catalogue.js';
 export { ConfigValidationError, DEFAULT_TELEMETRY_LOG_PATH, defineConfig, } from './config.js';
 export { EXIT_BREAK_BLOCKING, EXIT_BREAK_NON_BLOCKING, EXIT_UPHOLD, } from './exit-codes.js';
@@ -15,4 +15,4 @@ export { isPlainObject } from './is-plain-object.js';
 export { normalizeProtectedPaths } from './protected-paths.js';
 export { allFileChanges, parseInput, verdictToExitCode, } from './protocol.js';
 export { aggregateGain, appendRecord, appendRecordFailOpen, formatRecordLine, parseRecordLine, readRecords, runGain, SKIP_REASONS, } from './telemetry.js';
-export { noopTranscript, transcriptFromInput, } from './transcript.js';
+export { noopTranscript, transcriptFromInput, transcriptFromSession, } from './transcript.js';

package/dist/protocol.d.ts

@@ -91,6 +91,43 @@ export type CovenantInput = {
      * declaration's own supply policy.
      */
     actor?: Actor;
+    /**
+     * The host's tool roster — values, never vocabulary: `mutating` names the tools whose
+     * calls change a file, `shell` the ones carrying a command line, and `commandArgs` the
+     * argument keys that command line travels in. Absence leaves the runner on its own
+     * default roster.
+     */
+    tools?: {
+        mutating: string[];
+        shell: string[];
+        commandArgs: string[];
+    };
+    /**
+     * The evidence a live agent session carries that the repository's disk does not. Absence
+     * is the absence of a session; a session whose lists are empty is a host that named its
+     * evidence and could not deliver it.
+     *
+     * `evidencePath` is where that evidence was read from, so a surface can protect the file
+     * the session is judged from. `userMessages` carries `timestampMs` because a session can
+     * prove freshness a bare IR cannot, and `toolCalls` carries `succeeded` because a session
+     * can prove a call's outcome. `channels` is the host's own evidence channel text — a
+     * runner lifts it into the world it dispatches.
+     */
+    session?: {
+        evidencePath?: string;
+        userMessages: {
+            text: string;
+            timestampMs?: number;
+        }[];
+        toolCalls: {
+            name: string;
+            args?: Record<string, unknown>;
+            succeeded?: boolean;
+        }[];
+        channels?: {
+            sidecar?: string;
+        };
+    };
 };
 /**
  * `CovenantVerdict` — the result a covenant body produces.

package/dist/transcript.d.ts

@@ -64,3 +64,18 @@ export declare const noopTranscript: CanonicalTranscript;
  * being judged right now: they have not run, and a call can never be its own precedent.
  */
 export declare function transcriptFromInput(input: CovenantInput): CanonicalTranscript;
+/**
+ * Wrap a {@link CovenantInput}'s `session` as a {@link CanonicalTranscript}.
+ *
+ * Differs from {@link transcriptFromInput} on exactly the two facts a session proves and a
+ * bare IR cannot: `findUserMessages` carries `timestampMs` through, so a witness consumer
+ * can read freshness, and `findToolCalls` carries `succeeded` through, so a precedent
+ * consumer can read outcome. Both keys stay ABSENT where the session had none — a filled-in
+ * timestamp would open a valve from nothing, and a filled-in outcome would turn a call
+ * nobody observed into evidence. An absent `args` reads as `{}` because the transcript type
+ * requires the field.
+ *
+ * Order preserved; the input is never mutated, and every query returns fresh objects — args
+ * deep-copied — so consumers never hold live aliases into the shared IR.
+ */
+export declare function transcriptFromSession(session: NonNullable<CovenantInput['session']>): CanonicalTranscript;

package/dist/transcript.js

@@ -38,3 +38,29 @@ export function transcriptFromInput(input) {
             .map((call) => ({ name: call.name, args: structuredClone(call.args ?? {}) })),
     };
 }
+/**
+ * Wrap a {@link CovenantInput}'s `session` as a {@link CanonicalTranscript}.
+ *
+ * Differs from {@link transcriptFromInput} on exactly the two facts a session proves and a
+ * bare IR cannot: `findUserMessages` carries `timestampMs` through, so a witness consumer
+ * can read freshness, and `findToolCalls` carries `succeeded` through, so a precedent
+ * consumer can read outcome. Both keys stay ABSENT where the session had none — a filled-in
+ * timestamp would open a valve from nothing, and a filled-in outcome would turn a call
+ * nobody observed into evidence. An absent `args` reads as `{}` because the transcript type
+ * requires the field.
+ *
+ * Order preserved; the input is never mutated, and every query returns fresh objects — args
+ * deep-copied — so consumers never hold live aliases into the shared IR.
+ */
+export function transcriptFromSession(session) {
+    return {
+        findUserMessages: () => session.userMessages.map((message) => ({ ...message })),
+        findToolCalls: (name) => session.toolCalls
+            .filter((call) => name === undefined || call.name === name)
+            .map((call) => ({
+            name: call.name,
+            args: structuredClone(call.args ?? {}),
+            ...(call.succeeded === undefined ? {} : { succeeded: call.succeeded }),
+        })),
+    };
+}

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@polydeukes/core",
-  "version": "0.6.1",
-  "description": "Polydeukes core — covenant protocol, config loader, and transcript interface. Domain- and agent-agnostic. Alpha.",
+  "version": "0.8.0",
+  "description": "Polydeukes core — covenant protocol, config loader, and transcript interface. Domain- and agent-agnostic. Beta.",
+  "author": "huskyhoochu <dfg1499@gmail.com>",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -36,7 +37,7 @@
     "ajv": "8.20.0",
     "ajv-formats": "3.0.1",
     "typescript": "7.0.2",
-    "vitest": "^4.1.0"
+    "vitest": "^5.0.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",

package/schema/polydeukes.schema.json

@@ -33,6 +33,18 @@
       "uniqueItems": true,
       "items": { "$ref": "#/$defs/discipline" }
     },
+    "sessionDisciplines": {
+      "description": "Disciplines only the session surface observes — every entry whose declaration binds a transcript, channel, command, or actor evidence channel. Fully identical entries are copy-paste duplicates (by-id uniqueness and the placement rule are enforced by the runtime validator).",
+      "type": "array",
+      "uniqueItems": true,
+      "items": { "$ref": "#/$defs/discipline" }
+    },
+    "changeSetDisciplines": {
+      "description": "Disciplines only the change-set surface observes — every entry whose declaration binds the changes source. Fully identical entries are copy-paste duplicates (by-id uniqueness and the placement rule are enforced by the runtime validator).",
+      "type": "array",
+      "uniqueItems": true,
+      "items": { "$ref": "#/$defs/discipline" }
+    },
     "witness": { "$ref": "#/$defs/witness" }
   },
   "$defs": {