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

package/dist/simulation/toolkit/structured_output.js

@@ -0,0 +1,321 @@
+const MAX_DEPTH = 40;
+const OMIT_SCHEMA = { type: 'object', properties: { __ztcOptional: { type: 'string', const: 'omitted' } }, required: ['__ztcOptional'], additionalProperties: false };
+const COMPACT_KEYS = 'x-ztc-compact-keys';
+const KEYED_RELATIONSHIPS = 'x-ztc-keyed-relationships';
+/** Validate standard patterns even in absent fields and unused branches. */
+function validateConstraints(schema, depth) {
+    guardDepth(depth);
+    if (Object.hasOwn(schema, 'pattern')) {
+        if (typeof schema.pattern !== 'string')
+            throw new Error('Invalid string pattern');
+        new RegExp(schema.pattern, 'u');
+    }
+    schemaChildren(schema).forEach(child => validateConstraints(child, depth + 1));
+}
+function schemaChildren(schema) {
+    return [
+        ...(object(schema.properties) ? Object.values(schema.properties) : []),
+        ...(object(schema.items) ? [schema.items] : []),
+        ...(Array.isArray(schema.oneOf) ? schema.oneOf : []),
+        ...(Array.isArray(schema.anyOf) ? schema.anyOf : []),
+    ].filter(object);
+}
+function compactKey(index) {
+    let result = '';
+    do {
+        result = String.fromCharCode(97 + index % 26) + result;
+        index = Math.floor(index / 26) - 1;
+    } while (index >= 0);
+    return result;
+}
+function keyDictionary(schema) {
+    const names = new Set();
+    function collect(node, depth) {
+        guardDepth(depth);
+        if (node.additionalProperties === false && object(node.properties)) {
+            Object.keys(node.properties).forEach(key => names.add(key));
+        }
+        schemaChildren(node).forEach(child => collect(child, depth + 1));
+    }
+    collect(schema, 0);
+    return new Map([...names].sort().map((key, index) => [key, compactKey(index)]));
+}
+function renameSchema(schema, keys, depth) {
+    guardDepth(depth);
+    const result = { ...schema };
+    delete result[COMPACT_KEYS];
+    const closed = schema.additionalProperties === false;
+    if (object(schema.properties)) {
+        result.properties = Object.fromEntries(Object.entries(schema.properties).map(([key, child]) => [
+            closed ? keys.get(key) : key,
+            object(child) ? {
+                ...renameSchema(child, keys, depth + 1),
+                ...(closed ? { description: typeof child.description === 'string' ? `${key}: ${child.description}` : key } : {}),
+            } : child,
+        ]));
+        if (closed && Array.isArray(schema.required))
+            result.required = schema.required.map(key => keys.get(String(key)) ?? key);
+    }
+    if (object(schema.items))
+        result.items = renameSchema(schema.items, keys, depth + 1);
+    for (const keyword of ['oneOf', 'anyOf']) {
+        if (Array.isArray(schema[keyword]))
+            result[keyword] = schema[keyword].map(child => renameSchema(child, keys, depth + 1));
+    }
+    return result;
+}
+function restoreKeys(value, schema, keys, depth) {
+    guardDepth(depth);
+    const alternatives = schema.oneOf ?? schema.anyOf;
+    if (Array.isArray(alternatives)) {
+        const candidates = alternatives.filter(branch => matches(value, branch, depth + 1, true));
+        if (candidates.length === 0)
+            throw new Error('Simulation output matches no schema branch or contains an unknown key');
+        const restored = candidates.map(branch => restoreKeys(value, branch, keys, depth + 1));
+        if (new Set(restored.map(item => JSON.stringify(item))).size !== 1)
+            throw new Error('Simulation output has ambiguous compact keys');
+        return restored[0];
+    }
+    if (Array.isArray(value) && object(schema.items)) {
+        const items = schema.items;
+        return value.map(item => restoreKeys(item, items, keys, depth + 1));
+    }
+    if (object(value) && object(schema.properties)) {
+        const properties = schema.properties;
+        const closed = schema.additionalProperties === false;
+        const required = new Set(Array.isArray(schema.required) ? schema.required : []);
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => {
+            if (!Object.hasOwn(properties, key)) {
+                if (closed)
+                    throw new Error('Simulation output contains an unknown key');
+                return [key, item];
+            }
+            const child = properties[key];
+            const omitted = !required.has(key) && (item === null || matchesOmission(item));
+            const restored = object(child) && !omitted ? restoreKeys(item, child, keys, depth + 1) : item;
+            return [closed ? keys.get(key) : key, restored];
+        }));
+    }
+    return value;
+}
+function object(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function guardDepth(depth) {
+    if (depth > MAX_DEPTH)
+        throw new Error('Simulation output schema depth exceeded');
+}
+function valueType(value) {
+    return value === null ? 'null' : Array.isArray(value) ? 'array' : typeof value;
+}
+function compile(schema, depth) {
+    guardDepth(depth);
+    const output = { ...schema };
+    delete output[KEYED_RELATIONSHIPS];
+    // The provider subset omits uniqueness; canonical simulation validation retains it.
+    delete output.uniqueItems;
+    if (Array.isArray(output.enum) && output.enum.length === 0)
+        return null;
+    if ('const' in output) {
+        output.type = valueType(output.const);
+        if (Array.isArray(output.const)) {
+            output.minItems = output.const.length;
+            output.maxItems = output.const.length;
+            output.items = output.const.length === 0 ? { type: 'string' } : { anyOf: output.const.map(item => ({ const: item })) };
+            // Structured output accepts scalar constants only; source validation retains array order.
+            delete output.const;
+        }
+        if (object(output.const)) {
+            output.properties = Object.fromEntries(Object.entries(output.const).map(([key, value]) => [key, { const: value }]));
+            output.required = Object.keys(output.const);
+            delete output.const;
+        }
+    }
+    if (Array.isArray(output.enum) && output.type === undefined) {
+        const types = [...new Set(output.enum.map(valueType))];
+        output.type = types.length === 1 ? types[0] : types;
+    }
+    const alternatives = output.oneOf ?? output.anyOf;
+    if (Array.isArray(alternatives)) {
+        output.anyOf = alternatives.map(branch => compile(branch, depth + 1)).filter(branch => branch !== null);
+        delete output.oneOf;
+        if (output.anyOf.length === 0)
+            return null;
+    }
+    if (object(output.items)) {
+        output.items = compile(output.items, depth + 1);
+        if (output.items === null) {
+            if (Number(output.minItems ?? 0) > 0)
+                return null;
+            output.items = { type: 'string' };
+            output.maxItems = 0;
+        }
+    }
+    if (object(output.properties)) {
+        const required = new Set(Array.isArray(output.required) ? output.required : []);
+        const properties = [];
+        for (const [key, property] of Object.entries(output.properties)) {
+            if (!object(property))
+                throw new Error('Simulation output property needs an object schema');
+            const converted = compile(property, depth + 1);
+            if (required.has(key)) {
+                if (converted === null)
+                    return null;
+                properties.push([key, converted]);
+            }
+            else {
+                properties.push([key, converted === null ? { type: 'null' } : {
+                        anyOf: [converted, permitsNull(property, depth + 1) ? OMIT_SCHEMA : { type: 'null' }],
+                    }]);
+            }
+        }
+        output.properties = Object.fromEntries(properties);
+        output.required = properties.map(([key]) => key);
+        output.additionalProperties = false;
+    }
+    return output;
+}
+/** Translate the inference schema only. Canonical validators still own acceptance. */
+export function compileStrictSimulationSchema(schema) {
+    validateConstraints(schema, 0);
+    const result = compile(schema[COMPACT_KEYS] === true ? renameSchema(schema, keyDictionary(schema), 0) : schema, 0);
+    if (result === null)
+        throw new Error('Simulation output schema has no possible value');
+    return result;
+}
+function permitsNull(schema, depth) {
+    guardDepth(depth);
+    if ('const' in schema)
+        return schema.const === null;
+    if (Array.isArray(schema.enum))
+        return schema.enum.includes(null);
+    const alternatives = schema.oneOf ?? schema.anyOf;
+    if (Array.isArray(alternatives))
+        return alternatives.some(branch => permitsNull(branch, depth + 1));
+    return schema.type === 'null' || (Array.isArray(schema.type) && schema.type.includes('null'));
+}
+/** Select a union by its declared types and discriminants, not by model prose. */
+function matches(value, schema, depth, rejectUnknown = false) {
+    guardDepth(depth);
+    if ('const' in schema) {
+        if (object(schema.const) && object(value)) {
+            if (Object.keys(value).length !== Object.keys(schema.const).length
+                || !Object.entries(schema.const).every(([key, item]) => matches(value[key], { const: item }, depth + 1, rejectUnknown)))
+                return false;
+        }
+        else if (JSON.stringify(value) !== JSON.stringify(schema.const))
+            return false;
+    }
+    if (Array.isArray(schema.enum) && !schema.enum.includes(value))
+        return false;
+    if (typeof value === 'string' && typeof schema.pattern === 'string' && !new RegExp(schema.pattern, 'u').test(value))
+        return false;
+    if (schema.type !== undefined) {
+        const types = Array.isArray(schema.type) ? schema.type : [schema.type];
+        if (!types.includes(valueType(value)) && !(types.includes('integer') && Number.isInteger(value)))
+            return false;
+    }
+    const alternatives = schema.oneOf ?? schema.anyOf;
+    if (Array.isArray(alternatives) && !alternatives.some(branch => matches(value, branch, depth + 1, rejectUnknown)))
+        return false;
+    if (Array.isArray(value) && object(schema.items)) {
+        const items = schema.items;
+        if (!value.every(item => matches(item, items, depth + 1, rejectUnknown)))
+            return false;
+    }
+    if (object(value) && object(schema.properties)) {
+        if (rejectUnknown && schema.additionalProperties === false && Object.keys(value).some(key => !Object.hasOwn(schema.properties, key)))
+            return false;
+        const required = new Set(Array.isArray(schema.required) ? schema.required : []);
+        for (const [key, property] of Object.entries(schema.properties)) {
+            if (!Object.hasOwn(value, key)) {
+                if (required.has(key))
+                    return false;
+                else
+                    continue;
+            }
+            if (!required.has(key) && (value[key] === null || matchesOmission(value[key])))
+                continue;
+            if (object(property) && !matches(value[key], property, depth + 1, rejectUnknown))
+                return false;
+        }
+    }
+    return true;
+}
+function matchesOmission(value) {
+    return object(value) && Object.keys(value).length === 1 && value.__ztcOptional === 'omitted';
+}
+function decode(value, schema, depth) {
+    guardDepth(depth);
+    if (typeof value === 'string' && typeof schema.pattern === 'string' && !new RegExp(schema.pattern, 'u').test(value)) {
+        throw new Error('Simulation output violates string pattern');
+    }
+    const alternatives = schema.oneOf ?? schema.anyOf;
+    if (Array.isArray(alternatives)) {
+        const candidates = alternatives.filter(branch => matches(value, branch, depth + 1));
+        if (candidates.length === 0)
+            throw new Error('Simulation output matches no schema branch');
+        const decoded = candidates.map(branch => decode(value, branch, depth + 1));
+        if (new Set(decoded.map(item => JSON.stringify(item))).size !== 1)
+            throw new Error('Simulation output has ambiguous optional fields');
+        return decoded[0];
+    }
+    if (Array.isArray(value) && object(schema.items)) {
+        const items = schema.items;
+        return value.map(item => decode(item, items, depth + 1));
+    }
+    if (object(value) && object(schema.properties)) {
+        const required = new Set(Array.isArray(schema.required) ? schema.required : []);
+        const output = [];
+        for (const [key, item] of Object.entries(value)) {
+            const property = Object.hasOwn(schema.properties, key) ? schema.properties[key] : undefined;
+            if (object(property)) {
+                if (!required.has(key) && permitsNull(property, depth + 1) && matchesOmission(item))
+                    continue;
+                if (item === null && !required.has(key) && !permitsNull(property, depth + 1))
+                    continue;
+                output.push([key, decode(item, property, depth + 1)]);
+            }
+            else
+                output.push([key, item]);
+        }
+        return Object.fromEntries(output);
+    }
+    return value;
+}
+// JSON.parse validates syntax; this version-scoped scan preserves duplicate-key evidence.
+function assertUniqueJsonKeys(text) {
+    const containers = [];
+    for (const match of text.matchAll(/"(?:\\[\s\S]|[^"\\])*"|[{}\[\]]/g)) {
+        const token = match[0];
+        if (token === '{')
+            containers.push(new Set());
+        else if (token === '[')
+            containers.push(null);
+        else if (token === '}' || token === ']')
+            containers.pop();
+        else {
+            let following = match.index + token.length;
+            while (/\s/u.test(text[following] ?? ''))
+                following += 1;
+            if (text[following] !== ':')
+                continue;
+            const key = JSON.parse(token);
+            const keys = containers.at(-1);
+            if (keys.has(key))
+                throw new Error('Simulation output contains duplicate JSON keys');
+            keys.add(key);
+        }
+    }
+}
+export function decodeStrictSimulationOutput(text, schema) {
+    validateConstraints(schema, 0);
+    let value = JSON.parse(text);
+    if (schema[KEYED_RELATIONSHIPS] === 2)
+        assertUniqueJsonKeys(text);
+    if (schema[COMPACT_KEYS] === true) {
+        const keys = keyDictionary(schema);
+        value = restoreKeys(value, renameSchema(schema, keys, 0), new Map([...keys].map(([key, alias]) => [alias, key])), 0);
+    }
+    return JSON.stringify(decode(value, schema, 0));
+}

package/dist/simulation/types/world.d.ts

@@ -186,6 +186,8 @@ export interface SimBlueprint {
 export type DocumentType = string;
 /** A document in the company's document trail. Agents create and send these. */
 export interface DocumentEntry {
+    provenance?: import('../../plugin/simulation_documents.js').SimulationDocumentProvenanceV1;
+    ownerActorId?: string;
     id: string;
     /** Links to SimArtifact if formal (counts toward targets) */
     artifactId?: string;

package/dist/simulation/world/artifact_store.js

@@ -170,7 +170,7 @@ export class ArtifactStore {
         };
         this.documentTrail.push(entry);
         const maxDocumentTrail = 100;
-        if (this.documentTrail.length > maxDocumentTrail) {
+        if (this.documentTrail.length > maxDocumentTrail && !this.documentTrail.some(document => document.ownerActorId !== undefined)) {
             this.documentTrail = this.documentTrail.slice(-maxDocumentTrail);
             this.rebuildDocumentsByAgent();
         }

package/dist/simulation/world/memory_manager.d.ts

@@ -12,9 +12,11 @@ export interface MemoryTelemetrySnapshot {
     files: Array<[MemoryTelemetryFileName, number]>;
 }
 export interface MemoryManagerDeps {
+    provider?: string;
     invariantMode?: InvariantMode;
     outputDir?: string;
     backend?: MemoryBackendKind;
+    detached?: boolean;
 }
 declare const MEMORY_TELEMETRY_FILES: readonly ["memory_ops.jsonl", "memory_retrieval.jsonl", "memory_curator.jsonl", "prompt_packets.jsonl"];
 type MemoryTelemetryFileName = typeof MEMORY_TELEMETRY_FILES[number];
@@ -22,11 +24,14 @@ export declare class MemoryManager {
     private memories;
     private embeddings;
     private embeddingProvider;
+    private readonly provider?;
     private clock;
     private warnedOverflow;
     private invariantMode?;
     private backend;
     private outputDir?;
+    private readonly detached;
+    private detachedTelemetry?;
     constructor(clock: SimClock, deps?: MemoryManagerDeps);
     /** Swap the clock (used during checkpoint restore). */
     setClock(clock: SimClock): void;

package/dist/simulation/world/memory_manager.js

@@ -17,17 +17,22 @@ export class MemoryManager {
     memories = new Map();
     embeddings = new Map();
     embeddingProvider;
+    provider;
     clock;
     warnedOverflow = false;
     invariantMode;
     backend;
     outputDir;
+    detached;
+    detachedTelemetry;
     constructor(clock, deps) {
         this.clock = clock;
-        this.embeddingProvider = createEmbeddingProvider(this.embeddings);
+        this.provider = deps?.provider;
+        this.embeddingProvider = createEmbeddingProvider(this.embeddings, this.provider);
         this.invariantMode = deps?.invariantMode;
         this.backend = deps?.backend ?? resolveMemoryBackendKind();
         this.outputDir = deps?.outputDir;
+        this.detached = deps?.detached ?? false;
     }
     /** Swap the clock (used during checkpoint restore). */
     setClock(clock) {
@@ -155,7 +160,7 @@ export class MemoryManager {
             m.setEmbeddingsAccessor(() => this.embeddings);
             return [agentId, m];
         }));
-        this.embeddingProvider = createEmbeddingProvider(this.embeddings);
+        this.embeddingProvider = createEmbeddingProvider(this.embeddings, this.provider);
         this.warnedOverflow = false;
         this.restoreTelemetry(normalized.telemetry);
     }
@@ -166,6 +171,7 @@ export class MemoryManager {
             }
             return new FileSystemMemory(agentId, this.clock, {
                 outputDir: this.outputDir,
+                detached: this.detached,
                 personaSeed,
                 invariantMode: this.invariantMode,
             });
@@ -175,6 +181,7 @@ export class MemoryManager {
             getEmbeddings: () => this.embeddings,
             invariantMode: this.invariantMode,
             outputDir: this.outputDir,
+            detached: this.detached,
         });
     }
     restoreAgentMemory(agentId, snapshot) {
@@ -185,6 +192,7 @@ export class MemoryManager {
                 }
                 return FileSystemMemory.fromSnapshot(snapshot, this.clock, {
                     outputDir: this.outputDir,
+                    detached: this.detached,
                     invariantMode: this.invariantMode,
                 });
             case 'associative':
@@ -192,6 +200,7 @@ export class MemoryManager {
                     agentId,
                     invariantMode: this.invariantMode,
                     outputDir: this.outputDir,
+                    detached: this.detached,
                 });
             default:
                 throw new Error(`invalid memory backend kind for ${agentId}: ${String(snapshot.kind)}`);
@@ -239,6 +248,8 @@ export class MemoryManager {
         };
     }
     snapshotTelemetry() {
+        if (this.detached)
+            return structuredClone(this.detachedTelemetry);
         if (!this.outputDir)
             return undefined;
         const telemetryDir = join(this.outputDir, 'telemetry');
@@ -250,6 +261,10 @@ export class MemoryManager {
         };
     }
     restoreTelemetry(snapshot) {
+        if (this.detached) {
+            this.detachedTelemetry = structuredClone(snapshot);
+            return;
+        }
         if (!this.outputDir || !snapshot)
             return;
         const telemetryDir = join(this.outputDir, 'telemetry');

package/dist/simulation/world/state.d.ts

@@ -109,7 +109,7 @@ export declare class SimState {
     private _pendingMemoryWrites;
     private _pendingMemoryWriteErrors;
     private activeWorldTransition;
-    constructor(goal: SimGoal, config: SimConfig, preset?: DomainPreset, restoredWorldId?: string, restoredWorldContext?: WorldContextSnapshot);
+    constructor(goal: SimGoal, config: SimConfig, preset?: DomainPreset, restoredWorldId?: string, restoredWorldContext?: WorldContextSnapshot, detached?: boolean);
     private get worldContext();
     private get agentRegistry();
     private get artifactStore();
@@ -429,7 +429,8 @@ export declare class SimState {
     exportArtifacts(format?: 'jsonl' | 'json', outputPath?: string): string;
     createCheckpoint(extensions?: CheckpointExtensions): SimulationCheckpoint;
     saveCheckpoint(outputPath?: string, extensions?: CheckpointExtensions): string;
-    static loadCheckpoint(checkpointPath: string): Promise<SimState>;
+    static loadCheckpoint(checkpointPath: string, outputDirectory?: string): Promise<SimState>;
+    static fromCheckpoint(raw: unknown, outputDirectory?: string, detached?: boolean): Promise<SimState>;
     getStatus(): Record<string, unknown>;
     getRuntimePeriodNumber(): number | null;
     getCheckpointExtension(namespace: string): CheckpointExtension | null;

package/dist/simulation/world/state.js

@@ -373,7 +373,7 @@ export class SimState {
     _pendingMemoryWrites = new Set();
     _pendingMemoryWriteErrors = [];
     activeWorldTransition = null;
-    constructor(goal, config, preset, restoredWorldId, restoredWorldContext) {
+    constructor(goal, config, preset, restoredWorldId, restoredWorldContext, detached = false) {
         this.id = restoredWorldId
             ?? `sim-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
         this.goal = goal;
@@ -387,7 +387,7 @@ export class SimState {
         this.preset = preset ?? (config.domain
             ? DomainFactory.load(config.domain)
             : DomainFactory.createEmpty());
-        this.persistence = createSimulationPersistence(this.id, this.goal, this.config);
+        this.persistence = detached ? null : createSimulationPersistence(this.id, this.goal, this.config);
         if (restoredWorldContext !== undefined) {
             if (restoredWorldContext.config.worldId !== this.id) {
                 throw new Error('checkpoint: simulation identity does not match world context identity');
@@ -485,8 +485,10 @@ export class SimState {
         this.world = createWorld(definition, restoredWorldContext);
         const memCfg = this.preset.memoryConfig;
         this.memoryManager = new MemoryManager({ nowMs: () => this.calendar.getCurrentTime().getTime() }, {
+            provider: this.config.provider,
             invariantMode: memCfg?.invariants?.mode,
             outputDir: this.config.outputDir,
+            detached,
         });
     }
     get worldContext() {
@@ -1025,6 +1027,9 @@ export class SimState {
     }
     /** Add a document to the company trail. Records in creator's and recipients' memories. */
     addDocument(doc) {
+        if (doc.ownerActorId !== undefined) {
+            return this.artifactStore.addDocument(doc, new Date(this.calendar.getCurrentTime()));
+        }
         const document = this.withInheritedDocumentArtifact({
             ...doc,
             content: this.normalizeDocumentContent(doc.content),
@@ -1805,8 +1810,11 @@ export class SimState {
         this.persistence?.recordCheckpoint(requestedPath, checkpoint.savedAt);
         return requestedPath;
     }
-    static async loadCheckpoint(checkpointPath) {
+    static async loadCheckpoint(checkpointPath, outputDirectory) {
         const raw = JSON.parse(readBoundedCheckpoint(checkpointPath));
+        return SimState.fromCheckpoint(raw, outputDirectory);
+    }
+    static async fromCheckpoint(raw, outputDirectory, detached = false) {
         const checkpoint = parseSimulationCheckpoint(raw);
         if (checkpoint.schemaVersion !== SIMULATION_CHECKPOINT_VERSION) {
             throw new Error(`Unsupported simulation checkpoint version ${checkpoint.schemaVersion}; expected ${SIMULATION_CHECKPOINT_VERSION}`);
@@ -1817,7 +1825,9 @@ export class SimState {
         if (checkpoint.worldContext.currentTime !== checkpoint.calendar.current) {
             throw new Error('checkpoint: calendar time does not match world context time');
         }
-        const state = new SimState(checkpoint.goal, checkpoint.config, undefined, checkpoint.simulationId, checkpoint.worldContext);
+        const state = new SimState(checkpoint.goal, outputDirectory === undefined
+            ? checkpoint.config
+            : { ...checkpoint.config, outputDir: outputDirectory }, undefined, checkpoint.simulationId, checkpoint.worldContext, detached);
         state.externalAgentConfigs = checkpoint.externalAgentConfigs;
         state.agentRegistry.restore(checkpoint.agents);
         state.memoryManager.restore(checkpoint.memory);
@@ -1848,7 +1858,7 @@ export class SimState {
             : undefined);
         const pluginData = objectField(checkpoint.extensions['ztc.host']?.data, 'pluginData');
         const graphValue = objectField(pluginData, 'sim-graph');
-        if (checkpoint.config.features?.graph_memory && graphValue !== undefined) {
+        if (!detached && checkpoint.config.features?.graph_memory && graphValue !== undefined) {
             const graph = simulationFactGraphFromJson(graphValue);
             try {
                 await rebuildStateGraphSidecar(state, graph, { fresh: true });