@zergai/ztc 0.4.0-beta.1 → 0.5.0-beta.1

package/dist/simulation/telemetry.d.ts

@@ -12,13 +12,13 @@ export interface SimulationLlmCallContext {
     stage: SimulationLlmStage;
     periodNumber?: number;
     agentId?: string;
-    agentName?: string;
     meetingId?: string;
     requestId?: string;
     attempt?: number;
     component?: string;
 }
 export interface SimulationLlmCallRecord {
+    schemaVersion: 2;
     callId: string;
     timestampStart: string;
     timestampEnd: string;
@@ -31,7 +31,6 @@ export interface SimulationLlmCallRecord {
     attempt?: number;
     periodNumber?: number;
     agentId?: string;
-    agentName?: string;
     meetingId?: string;
     requestId?: string;
     maxTokensRequested: number;
@@ -40,28 +39,26 @@ export interface SimulationLlmCallRecord {
     usageOutputTokens: number;
     usageTotalTokens: number;
     usagePresent: boolean;
-    systemChars: number;
-    userChars: number;
-    responseChars: number;
-    systemPreview: string;
-    userPreview: string;
-    responsePreview: string;
-    error: string | null;
+    systemBytes: number;
+    userBytes: number;
+    responseBytes: number;
+    outcome: SimulationLlmOutcome;
 }
+export type SimulationLlmOutcome = 'success' | 'invalid-output' | 'provider-error' | 'timeout' | 'aborted' | 'circuit-open' | 'configuration-error';
 interface SimulationLlmCallInput {
     context: SimulationLlmCallContext;
     provider: string;
     model: string;
     reasoningEffort?: CodexReasoningEffort;
     maxTokensRequested: number;
-    system: string;
-    userMessage: string;
-    responseText?: string;
+    systemBytes: number;
+    userBytes: number;
+    responseBytes: number;
+    outcome: SimulationLlmOutcome;
     stopReason?: string;
     usage?: TokenUsage;
     startedAt: Date;
     endedAt: Date;
-    error?: unknown;
 }
 interface AggregateTotals {
     calls: number;
@@ -72,8 +69,8 @@ interface AggregateTotals {
     totalDurationMs: number;
 }
 export interface SimulationLlmSummary {
+    schemaVersion: 2;
     simulationId: string;
-    outputDir: string;
     updatedAt: string;
     totals: AggregateTotals;
     byStage: Record<string, AggregateTotals>;

package/dist/simulation/telemetry.js

@@ -1,19 +1,13 @@
-import { appendFileSync, existsSync, mkdirSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { appendFileSync, chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync, } from 'node:fs';
+import { join, resolve } from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { getSimState } from './world/state.js';
-const PREVIEW_MAX_CHARS = 240;
-let activeRun = null;
-let progressReporter = null;
-function compactWhitespace(value) {
-    return value.replace(/\s+/g, ' ').trim();
-}
-function preview(value) {
-    const compact = compactWhitespace(value);
-    if (compact.length <= PREVIEW_MAX_CHARS)
-        return compact;
-    return `${compact.slice(0, PREVIEW_MAX_CHARS - 3)}...`;
-}
+const activeRuns = new Map();
+const progressReporters = new Map();
+let latestSimulationId = null;
+const MAX_ACTIVE_RUNS = 64;
+const MAX_SUMMARY_BYTES = 1_048_576;
+const MAX_SUMMARY_GROUPS = 256;
 function makeEmptyTotals() {
     return {
         calls: 0,
@@ -34,36 +28,147 @@ function addToTotals(totals, record) {
         totals.totalTokens += record.usageTotalTokens;
     }
 }
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function parseCount(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0
+        ? value
+        : null;
+}
+function parseDuration(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0
+        ? value
+        : null;
+}
+function parseAggregateTotals(value) {
+    if (!isRecord(value))
+        return null;
+    const calls = parseCount(value.calls);
+    const callsWithUsage = parseCount(value.callsWithUsage);
+    const inputTokens = parseCount(value.inputTokens);
+    const outputTokens = parseCount(value.outputTokens);
+    const totalTokens = parseCount(value.totalTokens);
+    const totalDurationMs = parseDuration(value.totalDurationMs);
+    if (calls === null
+        || callsWithUsage === null
+        || inputTokens === null
+        || outputTokens === null
+        || totalTokens === null
+        || totalDurationMs === null
+        || callsWithUsage > calls) {
+        return null;
+    }
+    return {
+        calls,
+        callsWithUsage,
+        inputTokens,
+        outputTokens,
+        totalTokens,
+        totalDurationMs,
+    };
+}
+function parseAggregateGroups(value) {
+    if (!isRecord(value))
+        return null;
+    const entries = Object.entries(value);
+    if (entries.length > MAX_SUMMARY_GROUPS)
+        return null;
+    const groups = {};
+    for (const [key, candidate] of entries) {
+        if (safeTelemetryLabel(key, '') === '')
+            return null;
+        const totals = parseAggregateTotals(candidate);
+        if (totals === null)
+            return null;
+        groups[key] = totals;
+    }
+    return groups;
+}
+function readExistingSummary(summaryPath, simulationId) {
+    if (!existsSync(summaryPath))
+        return null;
+    try {
+        const metadata = lstatSync(summaryPath);
+        if (!metadata.isFile() || metadata.size > MAX_SUMMARY_BYTES)
+            return null;
+        const value = JSON.parse(readFileSync(summaryPath, 'utf8'));
+        if (!isRecord(value)
+            || value.schemaVersion !== 2
+            || value.simulationId !== simulationId
+            || typeof value.updatedAt !== 'string') {
+            return null;
+        }
+        const totals = parseAggregateTotals(value.totals);
+        const byStage = parseAggregateGroups(value.byStage);
+        const byPeriod = parseAggregateGroups(value.byPeriod);
+        if (totals === null || byStage === null || byPeriod === null)
+            return null;
+        return {
+            schemaVersion: 2,
+            simulationId,
+            updatedAt: value.updatedAt,
+            totals,
+            byStage,
+            byPeriod,
+        };
+    }
+    catch {
+        return null;
+    }
+}
 function ensureRun() {
     const state = getSimState();
     if (!state)
         return null;
-    if (activeRun && activeRun.simulationId === state.id)
-        return activeRun;
-    const telemetryDir = join(state.config.outputDir, 'telemetry');
+    const outputDir = resolve(state.config.outputDir);
+    const existing = activeRuns.get(state.id);
+    if (existing?.outputDir === outputDir) {
+        activeRuns.delete(state.id);
+        activeRuns.set(state.id, existing);
+        latestSimulationId = state.id;
+        return existing;
+    }
+    const telemetryDir = join(outputDir, 'telemetry');
+    if (existsSync(telemetryDir) && lstatSync(telemetryDir).isSymbolicLink()) {
+        throw new Error('Simulation telemetry directory cannot be a symbolic link');
+    }
     if (!existsSync(telemetryDir)) {
-        mkdirSync(telemetryDir, { recursive: true });
+        mkdirSync(telemetryDir, { recursive: true, mode: 0o700 });
     }
+    chmodSync(telemetryDir, 0o700);
     const callsPath = join(telemetryDir, 'llm_calls.jsonl');
     const summaryPath = join(telemetryDir, 'llm_summary.json');
-    const summary = {
+    for (const path of [callsPath, summaryPath]) {
+        if (existsSync(path) && lstatSync(path).isSymbolicLink()) {
+            throw new Error('Simulation telemetry files cannot be symbolic links');
+        }
+    }
+    const summary = readExistingSummary(summaryPath, state.id) ?? {
+        schemaVersion: 2,
         simulationId: state.id,
-        outputDir: state.config.outputDir,
         updatedAt: new Date().toISOString(),
         totals: makeEmptyTotals(),
         byStage: {},
         byPeriod: {},
     };
-    activeRun = {
+    const run = {
         simulationId: state.id,
-        outputDir: state.config.outputDir,
-        telemetryDir,
+        outputDir,
         callsPath,
         summaryPath,
         summary,
     };
-    writeFileSync(summaryPath, JSON.stringify(summary, null, 2));
-    return activeRun;
+    if (!activeRuns.has(state.id) && activeRuns.size >= MAX_ACTIVE_RUNS) {
+        const oldestSimulationId = activeRuns.keys().next().value;
+        if (oldestSimulationId !== undefined)
+            activeRuns.delete(oldestSimulationId);
+    }
+    activeRuns.set(state.id, run);
+    latestSimulationId = state.id;
+    writeFileSync(summaryPath, JSON.stringify(summary, null, 2), { mode: 0o600 });
+    chmodSync(summaryPath, 0o600);
+    return run;
 }
 function renderProgressLine(record) {
     const period = typeof record.periodNumber === 'number' ? ` p${record.periodNumber}` : '';
@@ -71,13 +176,19 @@ function renderProgressLine(record) {
     const usage = record.usagePresent
         ? `in=${record.usageInputTokens} out=${record.usageOutputTokens} total=${record.usageTotalTokens}`
         : 'usage=unknown';
-    if (record.error) {
-        return `  [llm] ${record.stage}${period}${effort} ${usage} ${record.durationMs}ms error=${record.error.slice(0, 120)}`;
-    }
-    return `  [llm] ${record.stage}${period}${effort} ${usage} ${record.durationMs}ms`;
+    return `  [llm] ${record.stage}${period}${effort} ${usage} ${record.durationMs}ms outcome=${record.outcome}`;
 }
 export function setSimulationTelemetryProgressReporter(reporter) {
-    progressReporter = reporter;
+    const simulationId = getSimState()?.id;
+    if (simulationId === undefined) {
+        if (reporter === null)
+            progressReporters.clear();
+        return;
+    }
+    if (reporter === null)
+        progressReporters.delete(simulationId);
+    else
+        progressReporters.set(simulationId, reporter);
 }
 export function recordSimulationLlmCall(input) {
     const run = ensureRun();
@@ -86,6 +197,7 @@ export function recordSimulationLlmCall(input) {
     const usage = input.usage;
     const usagePresent = Boolean(usage);
     const record = {
+        schemaVersion: 2,
         callId: randomUUID(),
         timestampStart: input.startedAt.toISOString(),
         timestampEnd: input.endedAt.toISOString(),
@@ -93,29 +205,30 @@ export function recordSimulationLlmCall(input) {
         provider: input.provider,
         model: input.model,
         reasoningEffort: input.reasoningEffort,
-        stage: input.context.stage,
-        component: input.context.component,
+        stage: safeTelemetryLabel(input.context.stage, 'unknown-stage'),
+        component: optionalTelemetryLabel(input.context.component),
         attempt: input.context.attempt,
         periodNumber: input.context.periodNumber,
-        agentId: input.context.agentId,
-        agentName: input.context.agentName,
-        meetingId: input.context.meetingId,
-        requestId: input.context.requestId,
+        agentId: optionalTelemetryLabel(input.context.agentId),
+        meetingId: optionalTelemetryLabel(input.context.meetingId),
+        requestId: optionalTelemetryLabel(input.context.requestId),
         maxTokensRequested: input.maxTokensRequested,
-        stopReason: input.stopReason,
+        stopReason: optionalTelemetryLabel(input.stopReason),
         usageInputTokens: usage?.inputTokens ?? 0,
         usageOutputTokens: usage?.outputTokens ?? 0,
         usageTotalTokens: usage?.totalTokens ?? 0,
         usagePresent,
-        systemChars: input.system.length,
-        userChars: input.userMessage.length,
-        responseChars: (input.responseText ?? '').length,
-        systemPreview: preview(input.system),
-        userPreview: preview(input.userMessage),
-        responsePreview: preview(input.responseText ?? ''),
-        error: input.error ? String(input.error) : null,
+        systemBytes: boundedCount(input.systemBytes),
+        userBytes: boundedCount(input.userBytes),
+        responseBytes: boundedCount(input.responseBytes),
+        outcome: input.outcome,
     };
-    appendFileSync(run.callsPath, `${JSON.stringify(record)}\n`);
+    appendFileSync(run.callsPath, `${JSON.stringify(record)}\n`, {
+        encoding: 'utf8',
+        flag: 'a',
+        mode: 0o600,
+    });
+    chmodSync(run.callsPath, 0o600);
     addToTotals(run.summary.totals, record);
     const stageKey = record.stage;
     if (!run.summary.byStage[stageKey]) {
@@ -130,15 +243,13 @@ export function recordSimulationLlmCall(input) {
         addToTotals(run.summary.byPeriod[periodKey], record);
     }
     run.summary.updatedAt = new Date().toISOString();
-    writeFileSync(run.summaryPath, JSON.stringify(run.summary, null, 2));
-    progressReporter?.(renderProgressLine(record));
+    writeFileSync(run.summaryPath, JSON.stringify(run.summary, null, 2), { mode: 0o600 });
+    chmodSync(run.summaryPath, 0o600);
+    progressReporters.get(run.simulationId)?.(renderProgressLine(record));
 }
 export function getSimulationTelemetrySummary(simulationId) {
-    if (!activeRun)
-        return null;
-    if (simulationId && activeRun.simulationId !== simulationId)
-        return null;
-    return activeRun.summary;
+    const id = simulationId ?? latestSimulationId;
+    return id === null ? null : activeRuns.get(id)?.summary ?? null;
 }
 export function buildSimulationTelemetrySummaryLines(summary) {
     const lines = [];
@@ -153,6 +264,18 @@ export function buildSimulationTelemetrySummaryLines(summary) {
     return lines;
 }
 export function resetSimulationTelemetryForTests() {
-    activeRun = null;
-    progressReporter = null;
+    activeRuns.clear();
+    progressReporters.clear();
+    latestSimulationId = null;
+}
+function safeTelemetryLabel(value, fallback) {
+    if (['__proto__', 'constructor', 'prototype'].includes(value))
+        return fallback;
+    return /^[A-Za-z0-9._:-]{1,128}$/.test(value) ? value : fallback;
+}
+function optionalTelemetryLabel(value) {
+    return value === undefined ? undefined : safeTelemetryLabel(value, 'invalid-label');
+}
+function boundedCount(value) {
+    return Number.isSafeInteger(value) && value >= 0 ? value : 0;
 }

package/dist/simulation/toolkit/bounded_turns.d.ts

@@ -0,0 +1,13 @@
+export type BoundedTurnErrorCode = 'invalid-turn' | 'turn-did-not-advance' | 'turn-limit-exceeded' | 'traversal-did-not-terminate';
+export declare class BoundedTurnError extends Error {
+    readonly code: BoundedTurnErrorCode;
+    constructor(code: BoundedTurnErrorCode, message: string);
+}
+export interface SeededRandom {
+    next(): number;
+    int(minimum: number, maximum: number): number;
+    pick<T>(values: readonly T[]): T;
+}
+export declare function makeSeededRandom(seed: string | number): SeededRandom;
+export declare function assertBoundedTurnAdvance(previousTurn: number, nextTurn: number, maximumTurns: number): void;
+export declare function assertBoundedTraversal(status: string, steps: number, maximumSteps: number, activeStatus?: string): void;

package/dist/simulation/toolkit/bounded_turns.js

@@ -0,0 +1,80 @@
+export class BoundedTurnError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'BoundedTurnError';
+    }
+}
+function numericSeed(seed) {
+    if (typeof seed === 'number') {
+        if (!Number.isFinite(seed)) {
+            throw new BoundedTurnError('invalid-turn', 'Simulation seed must be finite');
+        }
+        return seed >>> 0;
+    }
+    let hash = 2_166_136_261;
+    for (let index = 0; index < seed.length; index += 1) {
+        hash ^= seed.charCodeAt(index);
+        hash = Math.imul(hash, 16_777_619);
+    }
+    return hash >>> 0;
+}
+function makeMulberry32(seed) {
+    let state = seed >>> 0;
+    return () => {
+        state = (state + 0x6d2b79f5) | 0;
+        let mixed = Math.imul(state ^ (state >>> 15), 1 | state);
+        mixed = (mixed + Math.imul(mixed ^ (mixed >>> 7), 61 | mixed)) ^ mixed;
+        return ((mixed ^ (mixed >>> 14)) >>> 0) / 4_294_967_296;
+    };
+}
+export function makeSeededRandom(seed) {
+    const next = makeMulberry32(numericSeed(seed));
+    return {
+        next,
+        int(minimum, maximum) {
+            if (!Number.isSafeInteger(minimum)
+                || !Number.isSafeInteger(maximum)
+                || minimum > maximum
+                || maximum - minimum >= 4_294_967_296) {
+                throw new BoundedTurnError('invalid-turn', 'Random integer bounds must be ordered safe integers spanning fewer than 4294967296 values');
+            }
+            return minimum + Math.floor(next() * (maximum - minimum + 1));
+        },
+        pick(values) {
+            if (values.length === 0) {
+                throw new BoundedTurnError('invalid-turn', 'Cannot pick from an empty simulation choice set');
+            }
+            return values[Math.floor(next() * values.length)];
+        },
+    };
+}
+export function assertBoundedTurnAdvance(previousTurn, nextTurn, maximumTurns) {
+    if (!Number.isSafeInteger(previousTurn)
+        || !Number.isSafeInteger(nextTurn)
+        || !Number.isSafeInteger(maximumTurns)
+        || previousTurn < 0
+        || nextTurn < 0
+        || maximumTurns < 1) {
+        throw new BoundedTurnError('invalid-turn', 'Simulation turns must be non-negative safe integers with a positive maximum');
+    }
+    if (nextTurn > maximumTurns) {
+        throw new BoundedTurnError('turn-limit-exceeded', `Simulation turn ${nextTurn} exceeds the ${maximumTurns}-turn limit`);
+    }
+    if (nextTurn !== previousTurn + 1) {
+        throw new BoundedTurnError('turn-did-not-advance', `Simulation turn must advance exactly once from ${previousTurn} to ${previousTurn + 1}`);
+    }
+}
+export function assertBoundedTraversal(status, steps, maximumSteps, activeStatus = 'active') {
+    if (!Number.isSafeInteger(steps)
+        || !Number.isSafeInteger(maximumSteps)
+        || steps < 0
+        || maximumSteps < 1
+        || steps > maximumSteps) {
+        throw new BoundedTurnError('invalid-turn', 'Traversal steps must stay within a positive fixed budget');
+    }
+    if (status === activeStatus && steps === maximumSteps) {
+        throw new BoundedTurnError('traversal-did-not-terminate', `Simulation remained ${activeStatus} after ${maximumSteps} steps`);
+    }
+}

package/dist/simulation/toolkit/dynamic_agents.d.ts

@@ -0,0 +1,25 @@
+import type { SimulationAgentUpdateProposalV1, SimulationAgentBeliefV1, SimulationAgentRelationshipV1, SimulationGmProposalV1, SimulationGmConsequencesV1, SimulationPersistentAgentStateV1 } from '../../plugin/simulation_contract.js';
+export declare const DYNAMIC_MEMORY_WINDOW = 16;
+export declare const DYNAMIC_BELIEF_EVIDENCE_WINDOW = 100;
+export declare class DynamicAgentStateError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare function applyDynamicAgentUpdates(agents: readonly SimulationPersistentAgentStateV1[], proposal: SimulationGmConsequencesV1, options: {
+    readonly agencyVersion?: 'emergent-v1';
+    readonly knownEventIds: readonly string[];
+    readonly characterProposals?: readonly {
+        proposalId: string;
+        actorId: string;
+    }[];
+    readonly memoryHistory?: Readonly<Record<string, readonly SimulationPersistentAgentStateV1['memories'][number][]>>;
+    readonly beliefEvidenceHistory?: Readonly<Record<string, Readonly<Record<string, readonly string[]>>>>;
+}): SimulationPersistentAgentStateV1[];
+export declare function applyBeliefUpdate(belief: SimulationAgentBeliefV1, update: SimulationGmProposalV1['agentUpdates'][number]['beliefUpdates'][number] | undefined, archivedEvidence?: readonly string[]): SimulationAgentBeliefV1;
+export declare function applyRelationshipDelta(relationship: SimulationAgentRelationshipV1, delta: SimulationGmProposalV1['agentUpdates'][number]['relationshipDeltas'][number] | undefined, eventId: string): SimulationAgentRelationshipV1;
+export declare function validFailedAdjudicationCauses(update: Pick<SimulationAgentUpdateProposalV1, 'actorId' | 'sourceActionIds' | 'sourceAdjudicationProposalIds'> & {
+    readonly resourceDeltas?: Readonly<Record<string, number>>;
+}, proposal: Pick<SimulationGmConsequencesV1, 'adjudications' | 'domainActions'>, characters: readonly {
+    readonly proposalId: string;
+    readonly actorId: string;
+}[], humanActorIds: readonly string[], agencyVersion?: 'emergent-v1'): boolean;