paracosm 0.7.450 → 0.7.455

package/README.md

@@ -465,9 +465,9 @@ Non-SSE consumers (curl, Python integrations, third-party dashboards) can run a
 
 ```bash
 export PARACOSM_ENABLE_SIMULATE_ENDPOINT=true
-npx paracosm serve   # or bring up your own server via createMarsServer
+paracosm dashboard   # or bring up your own server via createMarsServer
 
-curl -s -X POST http://localhost:5188/simulate \
+curl -s -X POST http://localhost:3456/simulate \
   -H 'Content-Type: application/json' \
   -H 'X-Anthropic-Key: sk-ant-...' \
   -d '{

package/dist/engine/compiler/compile-from-seed.d.ts

@@ -69,10 +69,19 @@ export interface CompileFromSeedOptions extends CompileOptions {
  * the existing `compileScenario` pipeline with `seedText` threading
  * through for research grounding.
  *
- * Retries once on Zod-validation failure (surfaced through
- * `generateValidatedObject`'s maxRetries mechanism).
+ * Retries up to 3 times on Zod-validation failure. The first failure
+ * usually surfaces as an off-bound numeric (defaultPopulation pasted
+ * from a real-world headcount) or a non-kebab id; the explicit
+ * constraints in DRAFT_SYSTEM_PROMPT plus the retry budget recover
+ * cleanly in practice.
  *
- * @throws Error when the LLM fails to produce a valid draft after one retry.
+ * Wraps ObjectGenerationError with a more actionable message that
+ * preserves the raw model output so the caller can see what the LLM
+ * tried to produce.
+ *
+ * @throws Error when the LLM fails to produce a valid draft after the
+ *   retry budget is exhausted. Wraps any ObjectGenerationError so the
+ *   message names the field bounds that likely tripped validation.
  */
 export declare function compileFromSeed(input: CompileFromSeedInput, options?: CompileFromSeedOptions): Promise<ScenarioPackage>;
 //# sourceMappingURL=compile-from-seed.d.ts.map

package/dist/engine/compiler/compile-from-seed.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compile-from-seed.d.ts","sourceRoot":"","sources":["../../../src/engine/compiler/compile-from-seed.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAGnD;;;;GAIG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA0B9B,CAAC;AAEH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,wEAAwE;AACxE,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAcD,4FAA4F;AAC5F,MAAM,WAAW,sBAAuB,SAAQ,cAAc;IAC5D,qFAAqF;IACrF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,0FAA0F;IAC1F,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE,oBAAoB,EAC3B,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,eAAe,CAAC,CAyB1B"}
+{"version":3,"file":"compile-from-seed.d.ts","sourceRoot":"","sources":["../../../src/engine/compiler/compile-from-seed.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAInD;;;;GAIG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA0B9B,CAAC;AAEH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,wEAAwE;AACxE,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AA0CD,4FAA4F;AAC5F,MAAM,WAAW,sBAAuB,SAAQ,cAAc;IAC5D,qFAAqF;IACrF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,0FAA0F;IAC1F,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE,oBAAoB,EAC3B,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,eAAe,CAAC,CAwC1B"}

package/dist/engine/compiler/compile-from-seed.js

@@ -12,6 +12,7 @@
  */
 import { z } from 'zod';
 import { compileScenario } from './index.js';
+import { apiKeyForProvider, resolveProviderFromCredentials } from '../provider-credentials.js';
 import { generateValidatedObject } from '../../runtime/llm-invocations/generateValidatedObject.js';
 /**
  * The subset of a scenario JSON the LLM is asked to propose. Lean on
@@ -46,41 +47,90 @@ export const DraftScenarioSchema = z.object({
     theme: z.string().min(10).max(400).optional(),
 });
 /**
- * LLM system prompt for draft generation. Emphasizes: (a) match the
- * seed's domain, (b) pick domain-appropriate nouns, (c) keep scope
- * coherent so downstream compilation succeeds.
+ * LLM system prompt for draft generation. Emphasizes domain fit AND
+ * names every numeric / format constraint enforced by
+ * DraftScenarioSchema so the LLM doesn't waste retries on validation
+ * failures the schema would have caught (real-world counts pasted
+ * verbatim into defaultPopulation, capitalized ids, instructions
+ * bursting past 400 chars, etc.).
  */
 const DRAFT_SYSTEM_PROMPT = `You are a scenario architect for paracosm, a structured world-model simulator for AI agents.
-Given seed source material, propose a paracosm scenario JSON that matches the domain.
-Pick populationNoun, settlementNoun, and timeUnitNoun that fit the domain ("crew" / "habitat" / "day" for a submarine; "employees" / "company" / "quarter" for a corporate scenario; "colonists" / "colony" / "year" for a space settlement).
-Departments (2-8) should cover the decision-relevant roles in the domain. Metrics (2-12) should be quantifiable state the leader cares about.
-Setup: defaultTurns 4-8, defaultPopulation proportional to the scope, defaultStartTime appropriate for the domain.
-Keep all labels natural language; leave implementation details (hook code, citation sourcing) to downstream compilation.`;
+
+Given seed source material, propose a paracosm scenario JSON that matches the domain. The output is validated by Zod; producing any field outside the bounds below will be rejected.
+
+DOMAIN NOUNS
+- populationNoun (plural), settlementNoun (singular), timeUnitNoun (singular).
+- Examples: submarine -> "crew" / "habitat" / "day". Corporate -> "employees" / "company" / "quarter". Space settlement -> "colonists" / "colony" / "year". Game studio -> "players" / "studio" / "week". Public health -> "residents" / "state" / "day".
+
+ID FIELDS (id, departments[].id, metrics[].id)
+- kebab-case ONLY: lowercase letters, digits, hyphens. Length 3-64 (top-level), 2-48 (department), 2-32 (metric).
+- WRONG: "Stardrift Online", "Seasonal_Content". RIGHT: "stardrift-online", "seasonal-content".
+
+SETUP
+- defaultTurns: integer between 2 and 12. Pick 4-8 for most scenarios.
+- defaultPopulation: integer between 10 and 1000. This is a REPRESENTATIVE SAMPLE the simulation will agentize, NOT real-world headcount. A 380,000-MAU MMO becomes defaultPopulation: 200. A nation of millions becomes defaultPopulation: 500. Never paste real counts here.
+- defaultStartTime: integer appropriate for the domain (year for space, quarter index for corporate, day index for daily-cadence sims, etc.).
+
+DEPARTMENTS (2-8 entries)
+- label: 2-48 chars human-readable.
+- role: 2-80 chars short title.
+- instructions: 10-400 chars MAX. Keep terse and action-oriented.
+
+METRICS (2-12 entries)
+- format: one of "number", "percent", "currency".
+- Pick the metrics the leader actually steers on, not every available stat.
+
+LABELS
+- name: 2-80 chars, prose-y title for the scenario as a whole.
+- currency (optional): 1-16 chars, e.g. "USD".
+
+Keep all labels natural language. Leave hooks, citations, and implementation details to downstream compilation.`;
 /**
  * Compile a scenario from seed source material. Calls the LLM to
  * propose a `DraftScenario`, validates it via Zod, then routes into
  * the existing `compileScenario` pipeline with `seedText` threading
  * through for research grounding.
  *
- * Retries once on Zod-validation failure (surfaced through
- * `generateValidatedObject`'s maxRetries mechanism).
+ * Retries up to 3 times on Zod-validation failure. The first failure
+ * usually surfaces as an off-bound numeric (defaultPopulation pasted
+ * from a real-world headcount) or a non-kebab id; the explicit
+ * constraints in DRAFT_SYSTEM_PROMPT plus the retry budget recover
+ * cleanly in practice.
  *
- * @throws Error when the LLM fails to produce a valid draft after one retry.
+ * Wraps ObjectGenerationError with a more actionable message that
+ * preserves the raw model output so the caller can see what the LLM
+ * tried to produce.
+ *
+ * @throws Error when the LLM fails to produce a valid draft after the
+ *   retry budget is exhausted. Wraps any ObjectGenerationError so the
+ *   message names the field bounds that likely tripped validation.
  */
 export async function compileFromSeed(input, options = {}) {
-    const provider = options.draftProvider ?? options.provider ?? 'anthropic';
+    const provider = resolveProviderFromCredentials((options.draftProvider ?? options.provider), options, 'anthropic');
     const model = options.draftModel ?? options.model ?? 'claude-sonnet-4-6';
     const hint = input.domainHint ? `\n\nDomain hint: ${input.domainHint}` : '';
-    const prompt = `Seed source material:\n"""\n${input.seedText}\n"""${hint}\n\nRespond with a scenario JSON that matches DraftScenarioSchema.`;
-    const result = await generateValidatedObject({
-        provider,
-        model,
-        schema: DraftScenarioSchema,
-        schemaName: 'DraftScenario',
-        systemCacheable: DRAFT_SYSTEM_PROMPT,
-        prompt,
-        maxRetries: 1,
-    });
+    const prompt = `Seed source material:\n"""\n${input.seedText}\n"""${hint}\n\nRespond with a scenario JSON that matches DraftScenarioSchema. Remember: defaultPopulation must be 10-1000 (representative sample, NOT the real-world headcount from the seed). All ids must be kebab-case. Department instructions must be 10-400 chars.`;
+    let result;
+    try {
+        result = await generateValidatedObject({
+            provider,
+            model,
+            schema: DraftScenarioSchema,
+            schemaName: 'DraftScenario',
+            systemCacheable: DRAFT_SYSTEM_PROMPT,
+            prompt,
+            maxRetries: 3,
+            apiKey: apiKeyForProvider(provider, options),
+        });
+    }
+    catch (err) {
+        const rawText = err.rawText;
+        const baseMessage = err instanceof Error ? err.message : String(err);
+        const failureHint = ' (common cause: defaultPopulation > 1000 from a real-world count, or a non-kebab id like "Stardrift Online")';
+        const wrapped = new Error(`compileFromSeed: ${baseMessage}.${failureHint}${rawText ? `\nLast LLM raw output:\n${rawText.slice(0, 800)}` : ''}`);
+        wrapped.cause = err;
+        throw wrapped;
+    }
     // Route the validated draft into the existing compiler with
     // seedText grounding so the research + hook-generation stages
     // still pull citations and generate TypeScript.

package/dist/engine/compiler/compile-from-seed.js.map

@@ -1 +1 @@
-{"version":3,"file":"compile-from-seed.js","sourceRoot":"","sources":["../../../src/engine/compiler/compile-from-seed.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"compile-from-seed.js","sourceRoot":"","sources":["../../../src/engine/compiler/compile-from-seed.ts"],"names":[],"mappings":"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"}

package/dist/engine/provider-credentials.d.ts

@@ -0,0 +1,40 @@
+import type { LlmProvider } from './types.js';
+/** Provider credentials accepted by hosted routes and runtime calls. */
+export interface ProviderCredentialOptions {
+    /** OpenAI API key. Historical dashboard field name. */
+    apiKey?: string;
+    /** Anthropic API key. */
+    anthropicKey?: string;
+}
+/** Search-provider credentials accepted by setup/run paths. */
+export interface SearchCredentialOptions {
+    serperKey?: string;
+    firecrawlKey?: string;
+    tavilyKey?: string;
+    braveKey?: string;
+    cohereKey?: string;
+}
+export type RuntimeCredentialOptions = ProviderCredentialOptions & SearchCredentialOptions;
+/**
+ * Return a usable secret or undefined for empty and masked placeholder
+ * values. The dashboard persists masks such as "sk-..."; those must
+ * never replace a real server-side key.
+ */
+export declare function normalizeCredential(value: unknown): string | undefined;
+/** True when either supported LLM provider has a real explicit key. */
+export declare function hasProviderCredentials(credentials: ProviderCredentialOptions): boolean;
+/**
+ * Infer provider from explicit keys. A single real key is treated as
+ * user intent; when both are present, the caller's provider selection
+ * remains authoritative.
+ */
+export declare function inferProviderFromCredentials(credentials: ProviderCredentialOptions): LlmProvider | undefined;
+/** Resolve provider, preferring unambiguous explicit-key intent. */
+export declare function resolveProviderFromCredentials(requested: LlmProvider | undefined, credentials: ProviderCredentialOptions, fallback?: LlmProvider): LlmProvider;
+/** Return the explicit API key for the selected provider, if present. */
+export declare function apiKeyForProvider(provider: LlmProvider, credentials: ProviderCredentialOptions): string | undefined;
+/** Stable non-secret identity for cache keys that must vary by credential. */
+export declare function credentialFingerprint(value: string | undefined): string;
+/** Explicit search key first, then host env fallback. */
+export declare function searchCredential(explicitValue: unknown, envName: string, env?: NodeJS.ProcessEnv | undefined): string | undefined;
+//# sourceMappingURL=provider-credentials.d.ts.map

package/dist/engine/provider-credentials.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-credentials.d.ts","sourceRoot":"","sources":["../../src/engine/provider-credentials.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,wEAAwE;AACxE,MAAM,WAAW,yBAAyB;IACxC,uDAAuD;IACvD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yBAAyB;IACzB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,+DAA+D;AAC/D,MAAM,WAAW,uBAAuB;IACtC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,wBAAwB,GAAG,yBAAyB,GAAG,uBAAuB,CAAC;AAE3F;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAKtE;AAED,uEAAuE;AACvE,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,yBAAyB,GAAG,OAAO,CAEtF;AAED;;;;GAIG;AACH,wBAAgB,4BAA4B,CAC1C,WAAW,EAAE,yBAAyB,GACrC,WAAW,GAAG,SAAS,CAMzB;AAED,oEAAoE;AACpE,wBAAgB,8BAA8B,CAC5C,SAAS,EAAE,WAAW,GAAG,SAAS,EAClC,WAAW,EAAE,yBAAyB,EACtC,QAAQ,GAAE,WAAsB,GAC/B,WAAW,CAEb;AAED,yEAAyE;AACzE,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,WAAW,EACrB,WAAW,EAAE,yBAAyB,GACrC,MAAM,GAAG,SAAS,CAIpB;AAED,8EAA8E;AAC9E,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CASvE;AAED,yDAAyD;AACzD,wBAAgB,gBAAgB,CAC9B,aAAa,EAAE,OAAO,EACtB,OAAO,EAAE,MAAM,EACf,GAAG,GAAE,MAAM,CAAC,UAAU,GAAG,SAAoE,GAC5F,MAAM,GAAG,SAAS,CAEpB"}

package/dist/engine/provider-credentials.js

@@ -0,0 +1,58 @@
+/**
+ * Return a usable secret or undefined for empty and masked placeholder
+ * values. The dashboard persists masks such as "sk-..."; those must
+ * never replace a real server-side key.
+ */
+export function normalizeCredential(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const trimmed = value.trim();
+    if (!trimmed || trimmed.includes('...'))
+        return undefined;
+    return trimmed;
+}
+/** True when either supported LLM provider has a real explicit key. */
+export function hasProviderCredentials(credentials) {
+    return !!(normalizeCredential(credentials.apiKey) || normalizeCredential(credentials.anthropicKey));
+}
+/**
+ * Infer provider from explicit keys. A single real key is treated as
+ * user intent; when both are present, the caller's provider selection
+ * remains authoritative.
+ */
+export function inferProviderFromCredentials(credentials) {
+    const hasOpenAI = !!normalizeCredential(credentials.apiKey);
+    const hasAnthropic = !!normalizeCredential(credentials.anthropicKey);
+    if (hasOpenAI && !hasAnthropic)
+        return 'openai';
+    if (hasAnthropic && !hasOpenAI)
+        return 'anthropic';
+    return undefined;
+}
+/** Resolve provider, preferring unambiguous explicit-key intent. */
+export function resolveProviderFromCredentials(requested, credentials, fallback = 'openai') {
+    return inferProviderFromCredentials(credentials) ?? requested ?? fallback;
+}
+/** Return the explicit API key for the selected provider, if present. */
+export function apiKeyForProvider(provider, credentials) {
+    return provider === 'anthropic'
+        ? normalizeCredential(credentials.anthropicKey)
+        : normalizeCredential(credentials.apiKey);
+}
+/** Stable non-secret identity for cache keys that must vary by credential. */
+export function credentialFingerprint(value) {
+    const key = normalizeCredential(value);
+    if (!key)
+        return 'env';
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < key.length; i += 1) {
+        hash ^= key.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return (hash >>> 0).toString(16).padStart(8, '0');
+}
+/** Explicit search key first, then host env fallback. */
+export function searchCredential(explicitValue, envName, env = typeof process !== 'undefined' ? process.env : undefined) {
+    return normalizeCredential(explicitValue) ?? normalizeCredential(env?.[envName]);
+}
+//# sourceMappingURL=provider-credentials.js.map

package/dist/engine/provider-credentials.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-credentials.js","sourceRoot":"","sources":["../../src/engine/provider-credentials.ts"],"names":[],"mappings":"AAqBA;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAc;IAChD,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IAChD,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,IAAI,CAAC,OAAO,IAAI,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAC1D,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,sBAAsB,CAAC,WAAsC;IAC3E,OAAO,CAAC,CAAC,CAAC,mBAAmB,CAAC,WAAW,CAAC,MAAM,CAAC,IAAI,mBAAmB,CAAC,WAAW,CAAC,YAAY,CAAC,CAAC,CAAC;AACtG,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,4BAA4B,CAC1C,WAAsC;IAEtC,MAAM,SAAS,GAAG,CAAC,CAAC,mBAAmB,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;IAC5D,MAAM,YAAY,GAAG,CAAC,CAAC,mBAAmB,CAAC,WAAW,CAAC,YAAY,CAAC,CAAC;IACrE,IAAI,SAAS,IAAI,CAAC,YAAY;QAAE,OAAO,QAAQ,CAAC;IAChD,IAAI,YAAY,IAAI,CAAC,SAAS;QAAE,OAAO,WAAW,CAAC;IACnD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,8BAA8B,CAC5C,SAAkC,EAClC,WAAsC,EACtC,WAAwB,QAAQ;IAEhC,OAAO,4BAA4B,CAAC,WAAW,CAAC,IAAI,SAAS,IAAI,QAAQ,CAAC;AAC5E,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,iBAAiB,CAC/B,QAAqB,EACrB,WAAsC;IAEtC,OAAO,QAAQ,KAAK,WAAW;QAC7B,CAAC,CAAC,mBAAmB,CAAC,WAAW,CAAC,YAAY,CAAC;QAC/C,CAAC,CAAC,mBAAmB,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;AAC9C,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,qBAAqB,CAAC,KAAyB;IAC7D,MAAM,GAAG,GAAG,mBAAmB,CAAC,KAAK,CAAC,CAAC;IACvC,IAAI,CAAC,GAAG;QAAE,OAAO,KAAK,CAAC;IACvB,IAAI,IAAI,GAAG,UAAU,CAAC;IACtB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QACvC,IAAI,IAAI,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;QAC1B,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;IACrC,CAAC;IACD,OAAO,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;AACpD,CAAC;AAED,yDAAyD;AACzD,MAAM,UAAU,gBAAgB,CAC9B,aAAsB,EACtB,OAAe,EACf,MAAqC,OAAO,OAAO,KAAK,WAAW,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS;IAE7F,OAAO,mBAAmB,CAAC,aAAa,CAAC,IAAI,mBAAmB,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;AACnF,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paracosm",
-  "version": "0.7.450",
+  "version": "0.7.455",
   "description": "Prompt/document/URL-grounded structured world model for AI agents: typed ScenarioPackages, deterministic kernels, HEXACO leaders, LLM events, runtime tool forging, and reproducible counterfactual RunArtifacts. Built on AgentOS.",
   "type": "module",
   "main": "dist/engine/index.js",