@unbrained/pm-cli 2026.8.16 → 2026.8.18

package/dist/core/history/event-index.js

@@ -5,7 +5,7 @@
  * for cursor-resumable cross-item mutation event reads.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="f1205949-16d8-51ce-98e8-04abc4c78ee8")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="a84b308f-7eef-535c-9531-b33b0775c651")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { randomUUID } from "node:crypto";
@@ -13,9 +13,76 @@ import { createRequire } from "node:module";
 import { readHistoryEntries } from "./read.js";
 const EVENT_INDEX_FILENAME = "history-event-index.sqlite";
 const EVENT_INDEX_VERSION = "2";
+const AUTHORITATIVE_HISTORY_CACHE_LIMIT = 8;
+const authoritativeHistoryCaches = new Map();
 function eventIndexPath(pmRoot) {
     return path.join(pmRoot, "runtime", EVENT_INDEX_FILENAME);
 }
+async function readAuthoritativeHistoryEvents(pmRoot) {
+    const historyRoot = path.join(pmRoot, "history");
+    const entries = await fs
+        .readdir(historyRoot, { withFileTypes: true })
+        .catch((error) => {
+        if (typeof error === "object" &&
+            error !== null &&
+            "code" in error &&
+            error.code === "ENOENT") {
+            return [];
+        }
+        throw error;
+    });
+    const cached = authoritativeHistoryCaches.get(pmRoot) ?? {
+        streams: new Map(),
+        ordered_events: [],
+    };
+    const presentStreams = new Set();
+    let changed = !authoritativeHistoryCaches.has(pmRoot);
+    for (const historyFile of entries
+        .filter((entry) => entry.isFile() && entry.name.endsWith(".jsonl"))
+        .sort((left, right) => left.name.localeCompare(right.name))) {
+        const streamId = historyFile.name.slice(0, -".jsonl".length);
+        presentStreams.add(streamId);
+        const historyPath = path.join(historyRoot, historyFile.name);
+        const stats = await fs.stat(historyPath, { bigint: true });
+        const signature = [
+            stats.dev,
+            stats.ino,
+            stats.size,
+            stats.mtimeNs,
+            stats.ctimeNs,
+        ].join(":");
+        if (cached.streams.get(streamId)?.signature === signature)
+            continue;
+        const history = await readHistoryEntries(historyPath, streamId);
+        cached.streams.set(streamId, {
+            signature,
+            events: history.map((entry, streamOffset) => ({
+                stream_id: streamId,
+                stream_offset: streamOffset,
+                entry,
+            })),
+        });
+        changed = true;
+    }
+    for (const streamId of cached.streams.keys()) {
+        if (!presentStreams.has(streamId)) {
+            cached.streams.delete(streamId);
+            changed = true;
+        }
+    }
+    if (changed) {
+        cached.ordered_events = [...cached.streams.values()]
+            .flatMap((stream) => stream.events)
+            .sort(compareHistoryEventPosition);
+    }
+    authoritativeHistoryCaches.delete(pmRoot);
+    authoritativeHistoryCaches.set(pmRoot, cached);
+    if (authoritativeHistoryCaches.size > AUTHORITATIVE_HISTORY_CACHE_LIMIT) {
+        const oldestRoot = authoritativeHistoryCaches.keys().next().value;
+        authoritativeHistoryCaches.delete(oldestRoot);
+    }
+    return cached.ordered_events;
+}
 function loadDatabaseSync(loadModule) {
     try {
         const loaded = loadModule(["node", "sqlite"].join(":"));
@@ -85,21 +152,6 @@ export async function rebuildHistoryEventIndex(pmRoot) {
     const Database = resolveDatabaseSync();
     if (!Database)
         return false;
-    const historyRoot = path.join(pmRoot, "history");
-    const entries = await fs
-        .readdir(historyRoot, { withFileTypes: true })
-        .catch((error) => {
-        if (typeof error === "object" &&
-            error !== null &&
-            "code" in error &&
-            error.code === "ENOENT") {
-            return [];
-        }
-        throw error;
-    });
-    const historyFiles = entries
-        .filter((entry) => entry.isFile() && entry.name.endsWith(".jsonl"))
-        .sort((left, right) => left.name.localeCompare(right.name));
     const targetPath = eventIndexPath(pmRoot);
     await fs.mkdir(path.dirname(targetPath), { recursive: true });
     const temporaryPath = `${targetPath}.${randomUUID()}.tmp`;
@@ -108,16 +160,8 @@ export async function rebuildHistoryEventIndex(pmRoot) {
         database = new Database(temporaryPath);
         createSchema(database);
         database.exec("BEGIN IMMEDIATE");
-        for (const historyFile of historyFiles) {
-            const streamId = historyFile.name.slice(0, -".jsonl".length);
-            const history = await readHistoryEntries(path.join(historyRoot, historyFile.name), streamId);
-            for (const [streamOffset, entry] of history.entries()) {
-                insertEvent(database, {
-                    stream_id: streamId,
-                    stream_offset: streamOffset,
-                    entry,
-                });
-            }
+        for (const event of await readAuthoritativeHistoryEvents(pmRoot)) {
+            insertEvent(database, event);
         }
         database.exec("COMMIT");
         database.close();
@@ -132,6 +176,68 @@ export async function rebuildHistoryEventIndex(pmRoot) {
         throw error;
     }
 }
+function matchesSet(value, accepted) {
+    return !accepted || accepted.length === 0 || accepted.includes(value);
+}
+function compareHistoryEventPosition(left, right) {
+    return (left.entry.ts.localeCompare(right.entry.ts) ||
+        left.stream_id.localeCompare(right.stream_id) ||
+        left.stream_offset - right.stream_offset);
+}
+function isInsideHistoryEventWindow(event, query) {
+    if (query.after_ts !== undefined &&
+        query.after_stream_id !== undefined &&
+        query.after_stream_offset !== undefined) {
+        if (compareHistoryEventPosition(event, {
+            stream_id: query.after_stream_id,
+            stream_offset: query.after_stream_offset,
+            entry: { ...event.entry, ts: query.after_ts },
+        }) <= 0) {
+            return false;
+        }
+    }
+    else if (query.since_ts !== undefined &&
+        event.entry.ts < query.since_ts) {
+        return false;
+    }
+    return true;
+}
+function matchesHistoryEventHarness(event, query) {
+    if (!query.harnesses || query.harnesses.length === 0)
+        return true;
+    if (query.harnesses.includes(event.entry.agent_harness ?? ""))
+        return true;
+    return (event.entry.agent_harness === undefined &&
+        (query.harness_alias_authors ?? []).includes(event.entry.author));
+}
+function matchesHistoryEventQuery(event, query) {
+    if (!isInsideHistoryEventWindow(event, query) ||
+        !matchesSet(event.entry.op, query.ops) ||
+        !matchesSet(event.entry.author, query.authors) ||
+        !matchesSet(event.entry.agent_instance ?? "", query.agent_instances) ||
+        !matchesSet(event.stream_id, query.stream_ids) ||
+        !matchesHistoryEventHarness(event, query)) {
+        return false;
+    }
+    return (query.provenance ?? []).every((predicate) => {
+        const value = event.entry.agent_provenance?.[predicate.dimension]?.value;
+        return value !== undefined && predicate.values.includes(value);
+    });
+}
+/**
+ * Query authoritative history streams when the optional SQLite accelerator is
+ * unavailable. The result preserves the index contract at higher read cost.
+ */
+export async function queryHistoryEventStreams(pmRoot, query) {
+    const limit = Math.max(0, Math.floor(query.limit));
+    const rows = (await readAuthoritativeHistoryEvents(pmRoot))
+        .filter((event) => matchesHistoryEventQuery(event, query))
+        .slice(0, limit + 1);
+    return {
+        events: rows.slice(0, query.limit),
+        has_more: rows.length > query.limit,
+    };
+}
 /**
  * Update an already-built event projection after one authoritative append.
  * Absence is a cheap no-op; corrupt projections are removed for lazy rebuild.
@@ -268,4 +374,4 @@ export const _testOnly = {
     },
 };
 //# sourceMappingURL=event-index.js.map
-//# debugId=f1205949-16d8-51ce-98e8-04abc4c78ee8
+//# debugId=a84b308f-7eef-535c-9531-b33b0775c651

package/dist/core/history/replay.js

@@ -4,7 +4,7 @@
  * Implements append-only history and replay behavior for Replay.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="0c37a722-fda7-523e-991c-f8abfb7a1495")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="bf8797ec-53d3-5d23-8a6e-8296a027ddf2")}catch(e){}}();
 import jsonPatch from "fast-json-patch";
 import { ITEM_METADATA_KEY_ORDER } from "../shared/constants.js";
 import { canonicalDocument } from "../item/item-format.js";
@@ -123,11 +123,30 @@ export function tryApplyReplayPatch(current, patch) {
         return { ok: false, error };
     }
 }
+/** Return the distinct supported hash epochs explicitly declared by a stream. */
+function supportedExplicitHistoryItemHashVersions(entries) {
+    return [
+        ...new Set(entries
+            .map((entry) => entry.item_hash_version)
+            .filter((version) => version !== undefined &&
+            SUPPORTED_HISTORY_ITEM_HASH_VERSIONS.includes(version))),
+    ];
+}
+/** Select the hash epochs allowed for one entry under an authoritative stream marker. */
+function historyEntryHashCandidates(explicitVersion, authoritativeVersion) {
+    if (explicitVersion !== undefined) {
+        return [explicitVersion];
+    }
+    return authoritativeVersion === undefined
+        ? [1, CURRENT_HISTORY_ITEM_HASH_VERSION]
+        : [authoritativeVersion];
+}
 /** Deterministically verify a history chain: each entry's before_hash must equal the prior replayed after_hash, the patch must strictly apply, and the recorded after_hash must equal the replayed result. */
 /** Verify a chain and report the explicit or auto-detected item hash epoch. */
 export function verifyHistoryChainWithVersion(entries) {
     let replay = cloneEmptyReplayDocument();
     let detectedVersion;
+    let authoritativeExplicitVersion;
     for (let index = 0; index < entries.length; index += 1) {
         const entry = entries[index];
         const explicitVersion = entry.item_hash_version;
@@ -147,9 +166,10 @@ export function verifyHistoryChainWithVersion(entries) {
                 errors: [`verify_failed:patch_apply_failed:entry_${index + 1}`],
             };
         }
-        const candidates = explicitVersion === undefined
-            ? [CURRENT_HISTORY_ITEM_HASH_VERSION, 1]
-            : [explicitVersion];
+        // Prefer legacy epoch 1 when an unversioned entry is valid under both
+        // algorithms, but retain compatibility with transitional epoch-2 writers
+        // that shipped before item_hash_version became explicit.
+        const candidates = historyEntryHashCandidates(explicitVersion, authoritativeExplicitVersion);
         const beforeMatches = candidates.filter((version) => replayHash(replay, version) === entry.before_hash);
         if (beforeMatches.length === 0) {
             return {
@@ -166,6 +186,9 @@ export function verifyHistoryChainWithVersion(entries) {
         }
         replay = applied.document;
         detectedVersion = version;
+        if (explicitVersion !== undefined) {
+            authoritativeExplicitVersion = version;
+        }
     }
     return {
         ok: true,
@@ -228,19 +251,14 @@ export function lenientApplyReplayPatch(current, patch) {
  * irreconcilably mixed stream falls forward to the current epoch.
  */
 export function resolveHistoryRepairItemHashVersion(entries) {
+    const explicitVersions = supportedExplicitHistoryItemHashVersions(entries);
+    if (explicitVersions.length === 1) {
+        return explicitVersions[0];
+    }
     const verified = verifyHistoryChainWithVersion(entries);
     if (verified.ok && verified.item_hash_version !== undefined) {
         return verified.item_hash_version;
     }
-    const explicitVersions = [
-        ...new Set(entries
-            .map((entry) => entry.item_hash_version)
-            .filter((version) => version !== undefined &&
-            SUPPORTED_HISTORY_ITEM_HASH_VERSIONS.includes(version))),
-    ];
-    if (explicitVersions.length === 1) {
-        return explicitVersions[0];
-    }
     if (explicitVersions.length === 0) {
         return 1;
     }
@@ -333,4 +351,4 @@ export function historyEntriesToRaw(entries) {
     return `${entries.map((entry) => JSON.stringify(entry)).join("\n")}\n`;
 }
 //# sourceMappingURL=replay.js.map
-//# debugId=0c37a722-fda7-523e-991c-f8abfb7a1495
+//# debugId=bf8797ec-53d3-5d23-8a6e-8296a027ddf2

package/dist/core/schema/fields-file.d.ts

@@ -1,6 +1,6 @@
 import type { RuntimeFieldCommand, RuntimeFieldDefinition, RuntimeFieldType } from "../../types/index.js";
 export { normalizeStatusToken as normalizeFieldKey } from "./status-token.js";
-export type { RuntimeFieldCommand, RuntimeFieldDefinition, RuntimeFieldType, } from "../../types/index.js";
+export type { RuntimeFieldCommand, RuntimeFieldDefinition, RuntimeFieldValueSchema, RuntimeFieldType, } from "../../types/index.js";
 /** Built-in item-metadata field names a custom field key must never shadow. A custom key that collides with one of these would let `pm create --<key>` write over reserved metadata, so add-field rejects them up front (symmetric with the built-in-type guard in item-types-file.ts). */
 export declare const BUILTIN_FIELD_KEYS: ReadonlySet<string>;
 /** The shape persisted at `.agents/pm/schema/fields.json`. */

package/dist/core/schema/fields-file.js

@@ -4,7 +4,7 @@
  * Resolves configurable schema, fields, statuses, and workflows for Fields File.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="575b0c3a-9ce1-504f-a24e-d8854e898f17")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="2b5a573e-1e36-58b9-b93b-4a4088f71e9a")}catch(e){}}();
 import { RUNTIME_FIELD_COMMAND_VALUES, RUNTIME_FIELD_TYPE_VALUES, } from "../../types/index.js";
 import { ITEM_METADATA_KEY_ORDER } from "../shared/constants.js";
 import { normalizeStatusToken as normalizeFieldKey } from "./status-token.js";
@@ -286,4 +286,4 @@ function applyBooleanFlag(definition, key, value) {
     }
 }
 //# sourceMappingURL=fields-file.js.map
-//# debugId=575b0c3a-9ce1-504f-a24e-d8854e898f17
+//# debugId=2b5a573e-1e36-58b9-b93b-4a4088f71e9a

package/dist/core/schema/runtime-field-values.js

@@ -4,10 +4,13 @@
  * Resolves configurable schema, fields, statuses, and workflows for Runtime Field Values.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="9bef4fe4-11a8-51ae-a42a-a93cc9c57384")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="91a3969e-59b3-506e-9349-ca08e73a1228")}catch(e){}}();
 import { EXIT_CODE } from "../shared/constants.js";
 import { PmCliError } from "../shared/errors.js";
+import { stableStringify } from "../shared/serialization.js";
+import { isRfc3339DateTime } from "../shared/time.js";
 import { runtimeFieldOptionTarget, } from "./runtime-schema.js";
+const MAX_VALUE_SCHEMA_DEPTH = 16;
 function toCamelToken(value) {
     const segments = value
         .trim()
@@ -116,6 +119,109 @@ function parseJsonContainerValue(raw, label, expectedType) {
     }
     throw new PmCliError(`${label} must be valid JSON ${expectedType}`, EXIT_CODE.USAGE);
 }
+function valueMatchesSchemaType(value, type) {
+    if (type === undefined)
+        return true;
+    if (type === "array")
+        return Array.isArray(value);
+    if (type === "object") {
+        return typeof value === "object" && value !== null && !Array.isArray(value);
+    }
+    return typeof value === type;
+}
+function runtimeFieldPrimitiveSchemaError(value, schema, path) {
+    if (schema.const !== undefined &&
+        stableStringify(value) !== stableStringify(schema.const)) {
+        return `${path} must equal ${stableStringify(schema.const)}`;
+    }
+    if (schema.enum !== undefined &&
+        !schema.enum.some((candidate) => stableStringify(candidate) === stableStringify(value))) {
+        return `${path} must be one of ${schema.enum.map((entry) => stableStringify(entry)).join("|")}`;
+    }
+    if (!valueMatchesSchemaType(value, schema.type)) {
+        return `${path} must match configured type ${String(schema.type)}`;
+    }
+    if (typeof value === "string") {
+        if (schema.min_length !== undefined && value.length < schema.min_length) {
+            return `${path} must contain at least ${schema.min_length} characters`;
+        }
+        if (schema.format === "date-time" && !isRfc3339DateTime(value)) {
+            return `${path} must be an RFC 3339 date-time`;
+        }
+    }
+    return undefined;
+}
+function runtimeFieldArraySchemaError(value, schema, path, depth) {
+    if (!Array.isArray(value))
+        return undefined;
+    if (schema.min_items !== undefined && value.length < schema.min_items) {
+        return `${path} must contain at least ${schema.min_items} items`;
+    }
+    if (!schema.items)
+        return undefined;
+    for (const [index, entry] of value.entries()) {
+        const error = runtimeFieldSchemaError(entry, schema.items, `${path}[${index}]`, depth + 1);
+        if (error)
+            return error;
+    }
+    return undefined;
+}
+function runtimeFieldObjectSchemaError(value, schema, path, depth) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return undefined;
+    const record = value;
+    for (const key of schema.required ?? []) {
+        if (!Object.hasOwn(record, key))
+            return `${path}.${key} is required`;
+    }
+    for (const [key, entry] of Object.entries(record)) {
+        const propertySchema = schema.properties?.[key];
+        if (!propertySchema) {
+            if (schema.additional_properties === false)
+                return `${path}.${key} is not allowed`;
+            continue;
+        }
+        const error = runtimeFieldSchemaError(entry, propertySchema, `${path}.${key}`, depth + 1);
+        if (error)
+            return error;
+    }
+    return undefined;
+}
+/** Return the first semantic schema mismatch without mutating the input value. */
+function runtimeFieldSchemaError(value, schema, path, depth = 0) {
+    if (depth > MAX_VALUE_SCHEMA_DEPTH)
+        return `${path} value schema exceeds maximum depth`;
+    const directError = runtimeFieldPrimitiveSchemaError(value, schema, path);
+    if (directError)
+        return directError;
+    const arrayError = runtimeFieldArraySchemaError(value, schema, path, depth);
+    if (arrayError)
+        return arrayError;
+    const objectError = runtimeFieldObjectSchemaError(value, schema, path, depth);
+    if (objectError)
+        return objectError;
+    if (!schema.one_of)
+        return undefined;
+    let matches = 0;
+    for (const candidate of schema.one_of) {
+        if (runtimeFieldSchemaError(value, candidate, path, depth + 1) === undefined) {
+            matches += 1;
+            if (matches > 1)
+                break;
+        }
+    }
+    return matches === 1
+        ? undefined
+        : `${path} must match exactly one configured schema variant`;
+}
+function validateRuntimeFieldValue(definition, value, label) {
+    if (!definition.value_schema || value === undefined)
+        return value;
+    const error = runtimeFieldSchemaError(value, definition.value_schema, label);
+    if (error)
+        throw new PmCliError(error, EXIT_CODE.USAGE);
+    return value;
+}
 /** Implements coerce runtime field value for the public runtime surface of this module. */
 export function coerceRuntimeFieldValue(definition, rawValue, labelOverride) {
     const label = labelOverride ?? `--${definition.cli_flag}`;
@@ -126,17 +232,17 @@ export function coerceRuntimeFieldValue(definition, rawValue, labelOverride) {
         if (containerRaw === undefined) {
             return undefined;
         }
-        return parseJsonContainerValue(containerRaw, label, definition.type);
+        return validateRuntimeFieldValue(definition, parseJsonContainerValue(containerRaw, label, definition.type), label);
     }
     if (definition.repeatable || definition.type === "string_array") {
         const values = normalizeStringArrayValue(rawValue);
         if (definition.type === "number") {
-            return values.map((value) => parseNumberValue(value, label));
+            return validateRuntimeFieldValue(definition, values.map((value) => parseNumberValue(value, label)), label);
         }
         if (definition.type === "boolean") {
-            return values.map((value) => parseBooleanValue(value, label));
+            return validateRuntimeFieldValue(definition, values.map((value) => parseBooleanValue(value, label)), label);
         }
-        return values;
+        return validateRuntimeFieldValue(definition, values, label);
     }
     const scalarRaw = Array.isArray(rawValue)
         ? rawValue[rawValue.length - 1]
@@ -145,12 +251,12 @@ export function coerceRuntimeFieldValue(definition, rawValue, labelOverride) {
         return undefined;
     }
     if (definition.type === "number") {
-        return parseNumberValue(scalarRaw, label);
+        return validateRuntimeFieldValue(definition, parseNumberValue(scalarRaw, label), label);
     }
     if (definition.type === "boolean") {
-        return parseBooleanValue(scalarRaw, label);
+        return validateRuntimeFieldValue(definition, parseBooleanValue(scalarRaw, label), label);
     }
-    return typeof scalarRaw === "string" ? scalarRaw : String(scalarRaw);
+    return validateRuntimeFieldValue(definition, typeof scalarRaw === "string" ? scalarRaw : String(scalarRaw), label);
 }
 function shouldRequireFieldOnCreate(definition, itemTypeName) {
     if (!definition.required && !definition.required_on_create) {
@@ -205,4 +311,4 @@ export function collectRuntimeUpdateFieldValues(options, fieldRegistry, commands
     return values;
 }
 //# sourceMappingURL=runtime-field-values.js.map
-//# debugId=9bef4fe4-11a8-51ae-a42a-a93cc9c57384
+//# debugId=91a3969e-59b3-506e-9349-ca08e73a1228

package/dist/core/schema/runtime-schema.d.ts

@@ -1,4 +1,4 @@
-import type { ItemTypeDefinition, RuntimeFieldCommand, RuntimeFieldType, RuntimeSchemaSettings, RuntimeStatusDefinition, RuntimeStatusRole, RuntimeWorkflowDefinition } from "../../types/index.js";
+import type { ItemTypeDefinition, RuntimeFieldCommand, RuntimeFieldValueSchema, RuntimeFieldType, RuntimeSchemaSettings, RuntimeStatusDefinition, RuntimeStatusRole, RuntimeWorkflowDefinition } from "../../types/index.js";
 export type { RuntimeFieldCommand } from "../../types/index.js";
 /** Fallback runtime schema file paths used when callers do not provide an override. */
 export declare const DEFAULT_RUNTIME_SCHEMA_FILE_PATHS: Readonly<{
@@ -50,6 +50,8 @@ export interface RuntimeFieldDefinitionResolved {
     required_types: string[];
     /** Value that configures or reports allow unset for this contract. */
     allow_unset: boolean;
+    /** Optional semantic JSON-value constraints enforced on create and update. */
+    value_schema?: RuntimeFieldValueSchema;
 }
 /** Documents the runtime status registry payload exchanged by command, SDK, and package integrations. */
 export interface RuntimeStatusRegistry {

package/dist/core/schema/runtime-schema.js

@@ -4,7 +4,7 @@
  * Resolves configurable schema, fields, statuses, and workflows for Runtime Schema.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="a9ff482a-f9f9-5e35-88d0-240db815ec08")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="88b9179f-569e-5cd6-b67c-c27431961554")}catch(e){}}();
 import path from "node:path";
 import { pathExists, readFileIfExists, writeFileAtomic, } from "../fs/fs-utils.js";
 import { DEFAULT_STATUS_DEFINITIONS, DEFAULT_WORKFLOW_DEFINITION, } from "../shared/constants.js";
@@ -32,6 +32,119 @@ const RUNTIME_STATUS_ROLE_SET = new Set(RUNTIME_STATUS_ROLE_VALUES);
 const RUNTIME_FIELD_TYPE_SET = new Set(RUNTIME_FIELD_TYPE_VALUES);
 const RUNTIME_FIELD_COMMAND_SET = new Set(RUNTIME_FIELD_COMMAND_VALUES);
 const RUNTIME_UNKNOWN_FIELD_POLICY_SET = new Set(RUNTIME_UNKNOWN_FIELD_POLICY_VALUES);
+const RUNTIME_FIELD_VALUE_TYPE_SET = new Set([
+    "string",
+    "number",
+    "boolean",
+    "array",
+    "object",
+]);
+const MAX_RUNTIME_FIELD_VALUE_SCHEMA_DEPTH = 16;
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+const RUNTIME_FIELD_VALUE_SCHEMA_SHAPE_VALIDATORS = [
+    (schema) => schema.type === undefined ||
+        (typeof schema.type === "string" &&
+            RUNTIME_FIELD_VALUE_TYPE_SET.has(schema.type)),
+    (schema) => !Object.hasOwn(schema, "const") || isStructuredJsonValue(schema.const),
+    (schema) => schema.enum === undefined ||
+        (Array.isArray(schema.enum) &&
+            schema.enum.every((entry) => isStructuredJsonValue(entry))),
+    (schema) => schema.min_length === undefined ||
+        (Number.isInteger(schema.min_length) &&
+            schema.min_length >= 0),
+    (schema) => schema.min_items === undefined ||
+        (Number.isInteger(schema.min_items) && schema.min_items >= 0),
+    (schema) => schema.format === undefined || schema.format === "date-time",
+    (schema) => schema.required === undefined ||
+        (Array.isArray(schema.required) &&
+            schema.required.every((entry) => typeof entry === "string" && entry.length > 0)),
+    (schema) => schema.additional_properties === undefined ||
+        typeof schema.additional_properties === "boolean",
+    (schema) => schema.properties === undefined ||
+        isPlainObject(schema.properties),
+    (schema) => schema.one_of === undefined ||
+        (Array.isArray(schema.one_of) && schema.one_of.length > 0),
+];
+function isStructuredJsonValue(value, ancestors = new Set()) {
+    if (value === null ||
+        typeof value === "string" ||
+        typeof value === "boolean") {
+        return true;
+    }
+    if (typeof value === "number")
+        return Number.isFinite(value);
+    if (typeof value !== "object" || ancestors.has(value))
+        return false;
+    ancestors.add(value);
+    const valid = Array.isArray(value)
+        ? value.every((entry) => isStructuredJsonValue(entry, ancestors))
+        : Object.values(value).every((entry) => isStructuredJsonValue(entry, ancestors));
+    ancestors.delete(value);
+    return valid;
+}
+/** Normalize an untrusted recursive custom-field value schema or reject it. */
+function normalizeRuntimeFieldValueSchema(value, depth = 0, ancestors = new Set()) {
+    if (!isPlainObject(value) ||
+        depth > MAX_RUNTIME_FIELD_VALUE_SCHEMA_DEPTH ||
+        ancestors.has(value)) {
+        return undefined;
+    }
+    ancestors.add(value);
+    const schema = value;
+    const type = schema.type;
+    const enumValues = schema.enum;
+    const oneOf = schema.one_of;
+    const properties = schema.properties;
+    const items = schema.items;
+    const required = schema.required;
+    const minLength = schema.min_length;
+    const minItems = schema.min_items;
+    const format = schema.format;
+    const additionalProperties = schema.additional_properties;
+    if (!RUNTIME_FIELD_VALUE_SCHEMA_SHAPE_VALIDATORS.every((check) => check(schema))) {
+        ancestors.delete(value);
+        return undefined;
+    }
+    const normalizedProperties = properties === undefined
+        ? undefined
+        : Object.fromEntries(Object.entries(properties).map(([key, entry]) => [
+            key,
+            normalizeRuntimeFieldValueSchema(entry, depth + 1, ancestors),
+        ]));
+    const normalizedItems = items === undefined
+        ? undefined
+        : normalizeRuntimeFieldValueSchema(items, depth + 1, ancestors);
+    const normalizedOneOf = oneOf === undefined
+        ? undefined
+        : oneOf.map((entry) => normalizeRuntimeFieldValueSchema(entry, depth + 1, ancestors));
+    const normalizedNestedSchemas = [
+        ...Object.values(normalizedProperties ?? {}),
+        ...(items === undefined ? [] : [normalizedItems]),
+        ...(normalizedOneOf ?? []),
+    ];
+    if (normalizedNestedSchemas.some((entry) => entry === undefined)) {
+        ancestors.delete(value);
+        return undefined;
+    }
+    ancestors.delete(value);
+    return Object.fromEntries(Object.entries({
+        type: type,
+        const: Object.hasOwn(schema, "const") ? schema.const : undefined,
+        enum: enumValues,
+        min_length: minLength,
+        min_items: minItems,
+        format: format,
+        properties: normalizedProperties,
+        required: required === undefined
+            ? undefined
+            : [...new Set(required)],
+        additional_properties: additionalProperties,
+        items: normalizedItems,
+        one_of: normalizedOneOf,
+    }).filter(([, entry]) => entry !== undefined));
+}
 function normalizeStringList(values) {
     const candidates = Array.isArray(values) ? values : [];
     return [
@@ -202,6 +315,12 @@ function normalizeRuntimeFieldDefinition(definition) {
     })();
     const description = definition.description?.trim();
     const requiredTypes = normalizeStringList(definition.required_types);
+    const valueSchema = definition.value_schema === undefined
+        ? undefined
+        : normalizeRuntimeFieldValueSchema(definition.value_schema);
+    if (definition.value_schema !== undefined && valueSchema === undefined) {
+        return null;
+    }
     return {
         key,
         metadata_key: metadataKey,
@@ -210,11 +329,12 @@ function normalizeRuntimeFieldDefinition(definition) {
         description: description && description.length > 0 ? description : undefined,
         type,
         commands,
-        repeatable: definition.repeatable === true || type === "string_array",
+        repeatable: [definition.repeatable === true, type === "string_array"].includes(true),
         required: definition.required === true,
         required_on_create: definition.required_on_create === true,
         required_types: requiredTypes,
         allow_unset: definition.allow_unset !== false,
+        value_schema: valueSchema,
     };
 }
 function normalizeRuntimeStatusDefinitions(statusesSource) {
@@ -277,6 +397,7 @@ function serializeRuntimeFieldDefinition(definition) {
             ? [...definition.required_types]
             : undefined,
         allow_unset: definition.allow_unset === false ? false : undefined,
+        value_schema: definition.value_schema,
     };
 }
 function normalizeUnknownFieldPolicy(policy) {
@@ -691,4 +812,4 @@ export function statusIsTerminal(status, registry) {
     return registry.terminal_statuses.has(normalized);
 }
 //# sourceMappingURL=runtime-schema.js.map
-//# debugId=a9ff482a-f9f9-5e35-88d0-240db815ec08
+//# debugId=88b9179f-569e-5cd6-b67c-c27431961554