@unbrained/pm-cli 2026.8.15 → 2026.8.17

package/dist/core/extensions/loader.js

@@ -4,7 +4,7 @@
  * Implements extension runtime contracts and governance for Loader.
  */
 
-!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]="2b8750c3-7b19-5240-8179-f83830af1b77")}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]="c88047fc-2bbd-5781-96a8-01685c06fb33")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
@@ -28,6 +28,7 @@ import { normalizeExtensionPolicy, serializeExtensionPolicy, hydrateExtensionPol
 import { createEmptyExtensionHookRegistry, createEmptyExtensionCommandRegistry, createEmptyExtensionParserRegistry, createEmptyExtensionPreflightRegistry, createEmptyExtensionServiceRegistry, createEmptyExtensionRendererRegistry, createEmptyExtensionRegistrationRegistry, } from "./extension-registries.js";
 import { normalizeCommandName, cloneContextSnapshot, } from "./extension-runtime-helpers.js";
 import { normalizeExtensionContributionInventory } from "./contribution-inventory.js";
+import { formatExtensionManifestSchemaWarnings } from "./manifest-schema.js";
 import { attachRuntimeDefinition, assertHookHandler, assertNonEmptyRegistrationString, assertRegistrationFunction, cloneRuntimeRegistrationValue, createRegistrationValidationError, extractRegistrationValidationTrace, isExtensionServiceName, isOutputRendererFormat, normalizeRegistrationRecord, normalizeRegistrationRecordList, normalizeRuntimeRegistrationRecord, normalizeRegistrationName, sanitizeRegistrationValue, toRegistrationCommandPath, validateAssuranceMeasurementProviderDefinition, } from "./registration-values.js";
 import { buildReadyExtensionCandidate, } from "./extension-candidate.js";
 export { parseUnknownExtensionCapabilityWarning, parseLegacyExtensionCapabilityAliasWarning, } from "./extension-capability-aliases.js";
@@ -513,8 +514,8 @@ function buildUnavailableExtensionScan(layer, directory, manifestPath, warning)
     };
 }
 /** Collect the non-fatal load warnings for a parsed extension manifest, in detection order: legacy capability aliases, unknown capabilities, an entry outside or absent from the extension directory, then the pm version floor/ceiling incompatibility warnings. */
-function collectScannedExtensionWarnings(layer, manifest, entryWithinDirectory, entryExists, pmVersionCompatibility, pmMaxVersionCompatibility) {
-    const extensionWarnings = [];
+function collectScannedExtensionWarnings(layer, manifest, rawManifest, entryWithinDirectory, entryExists, pmVersionCompatibility, pmMaxVersionCompatibility) {
+    const extensionWarnings = formatExtensionManifestSchemaWarnings(layer, manifest, rawManifest);
     if (Array.isArray(manifest.legacy_capability_aliases) &&
         manifest.legacy_capability_aliases.length > 0) {
         extensionWarnings.push(formatLegacyExtensionCapabilityAliasWarning(layer, manifest.name, manifest.legacy_capability_aliases));
@@ -543,14 +544,17 @@ async function scanExtensionDirectory(layer, extensionsRoot, directory, enabled,
         return buildUnavailableExtensionScan(layer, directory, manifestPath, `extension_manifest_missing:${layer}:${directory}`);
     }
     let manifest;
+    let rawManifest;
     try {
         const parsed = JSON.parse(await fs.readFile(manifestPath, "utf8"));
+        rawManifest = asRecordLoose(parsed);
         manifest = parseExtensionManifestDocument(parsed);
     }
     catch {
+        rawManifest = null;
         manifest = null;
     }
-    if (!manifest) {
+    if (!manifest || !rawManifest) {
         return buildUnavailableExtensionScan(layer, directory, manifestPath, `extension_manifest_invalid:${layer}:${directory}`);
     }
     const entryPath = path.resolve(extensionDir, manifest.entry);
@@ -564,7 +568,7 @@ async function scanExtensionDirectory(layer, extensionsRoot, directory, enabled,
     const enabledForLoad = shouldEnable(manifest.name, enabled, disabled);
     const pmVersionCompatibility = await evaluatePmMinVersionCompatibility(layer, manifest);
     const pmMaxVersionCompatibility = await evaluatePmMaxVersionCompatibility(layer, manifest, pmMaxVersionExceededMode);
-    const extensionWarnings = collectScannedExtensionWarnings(layer, manifest, entryWithinDirectory, entryExists, pmVersionCompatibility, pmMaxVersionCompatibility);
+    const extensionWarnings = collectScannedExtensionWarnings(layer, manifest, rawManifest, entryWithinDirectory, entryExists, pmVersionCompatibility, pmMaxVersionCompatibility);
     const extensionReady = entryWithinDirectory &&
         entryExists &&
         pmVersionCompatibility.allowed &&
@@ -2221,4 +2225,4 @@ export const _testOnlyLoader = {
     },
 };
 //# sourceMappingURL=loader.js.map
-//# debugId=2b8750c3-7b19-5240-8179-f83830af1b77
+//# debugId=c88047fc-2bbd-5781-96a8-01685c06fb33

package/dist/core/extensions/manifest-schema.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @module core/extensions/manifest-schema
+ *
+ * Defines the closed extension-manifest key vocabulary and returns pure schema
+ * diagnostics shared by SDK authoring checks and runtime discovery.
+ */
+import type { ExtensionLayer, ExtensionManifest } from "./extension-types.js";
+/** Canonical top-level keys accepted by an extension `manifest.json`. */
+export declare const KNOWN_EXTENSION_MANIFEST_KEYS: Set<string>;
+/** Pure closed-schema inspection result for one raw extension manifest. */
+export interface ExtensionManifestSchemaInspection {
+    /** Unknown top-level keys in deterministic lexical order. */
+    unknownKeys: string[];
+    /** Whether neither canonical pm compatibility bound is present. */
+    missingVersionBounds: boolean;
+}
+/** Inspect raw manifest keys without parsing, loading, or mutating an extension. */
+export declare function inspectExtensionManifestSchema(manifest: Readonly<Record<string, unknown>>): ExtensionManifestSchemaInspection;
+/** Format runtime discovery warnings for unknown keys and absent canonical compatibility bounds. */
+export declare function formatExtensionManifestSchemaWarnings(layer: ExtensionLayer, manifest: ExtensionManifest, rawManifest: Readonly<Record<string, unknown>>): string[];

package/dist/core/extensions/manifest-schema.js

@@ -0,0 +1,52 @@
+/**
+ * @module core/extensions/manifest-schema
+ *
+ * Defines the closed extension-manifest key vocabulary and returns pure schema
+ * diagnostics shared by SDK authoring checks and runtime discovery.
+ */
+/** Canonical top-level keys accepted by an extension `manifest.json`. */
+
+!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]="7d9d8924-3186-5aab-ac36-164fb08624a8")}catch(e){}}();
+export const KNOWN_EXTENSION_MANIFEST_KEYS = new Set([
+    "name",
+    "version",
+    "entry",
+    "priority",
+    "description",
+    "author",
+    "capabilities",
+    "manifest_version",
+    "pm_min_version",
+    "pm_max_version",
+    "engines",
+    "trusted",
+    "provenance",
+    "sandbox_profile",
+    "permissions",
+    "activation",
+    "contributions",
+    "legacy_capability_aliases",
+]);
+/** Inspect raw manifest keys without parsing, loading, or mutating an extension. */
+export function inspectExtensionManifestSchema(manifest) {
+    return {
+        unknownKeys: Object.keys(manifest)
+            .filter((key) => !KNOWN_EXTENSION_MANIFEST_KEYS.has(key))
+            .sort((left, right) => (left > right ? 1 : -1)),
+        missingVersionBounds: manifest.pm_min_version === undefined &&
+            manifest.pm_max_version === undefined,
+    };
+}
+/** Format runtime discovery warnings for unknown keys and absent canonical compatibility bounds. */
+export function formatExtensionManifestSchemaWarnings(layer, manifest, rawManifest) {
+    const inspection = inspectExtensionManifestSchema(rawManifest);
+    const warnings = inspection.unknownKeys.map((key) => key === "compatibility"
+        ? `extension_manifest_unknown_key:${layer}:${manifest.name}:key=compatibility:suggested=pm_min_version`
+        : `extension_manifest_unknown_key:${layer}:${manifest.name}:key=${key}`);
+    if (inspection.missingVersionBounds) {
+        warnings.push(`extension_manifest_no_version_bounds:${layer}:${manifest.name}:suggested=pm_min_version`);
+    }
+    return warnings;
+}
+//# sourceMappingURL=manifest-schema.js.map
+//# debugId=7d9d8924-3186-5aab-ac36-164fb08624a8

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/history/workspace-history.js

@@ -5,7 +5,7 @@
  * HistoryEntry format used by item mutations.
  */
 
-!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]="0f666995-78f8-5741-ae0c-0d792feea599")}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]="9027d972-ce29-5511-ba81-27e17d97446e")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { readFileIfExists, writeFileAtomic } from "../fs/fs-utils.js";
@@ -54,6 +54,28 @@ function workspaceDocuments(document) {
         ? document.metadata.documents
         : {};
 }
+/** Refuse a workspace mutation or replay whose append-only chain is invalid. */
+function throwWorkspaceHistoryVerificationFailure(errors) {
+    throw new PmCliError(`Workspace history verification failed: ${errors.join(", ")}`, EXIT_CODE.CONFLICT, {
+        code: "workspace_history_chain_invalid",
+        reason: "workspace_history_chain_verification_failed",
+        verification_errors: [...errors],
+        required: "Repair the _workspace history chain before reading, reconciling, restoring, or appending audited singleton state.",
+        why: "Continuing against an unverifiable append-only stream could hide or compound workspace state corruption.",
+        examples: [
+            "pm history _workspace --verify --json",
+            "pm validate --check-history-drift --fix-hints --json",
+        ],
+        nextSteps: [
+            "Inspect the exact verification_errors and preserve the corrupt stream as evidence.",
+            "Use the history-drift remediation returned by validate before retrying the refused operation.",
+        ],
+        recovery: {
+            recovery_mode: "compact",
+            next_best_command: "pm history _workspace --verify --json",
+        },
+    });
+}
 /** Resolve a governed singleton path and reject paths outside the tracker root. */
 function resolveGovernedDocumentPath(pmRoot, filePath) {
     const absolutePath = path.resolve(filePath);
@@ -76,7 +98,7 @@ export async function inspectWorkspaceHistoryState(pmRoot) {
     const entries = await readHistoryEntries(getWorkspaceHistoryPath(pmRoot), WORKSPACE_HISTORY_ID);
     const verification = verifyHistoryChain(entries);
     if (!verification.ok) {
-        throw new TypeError(`Workspace history verification failed: ${verification.errors.join(", ")}`);
+        throwWorkspaceHistoryVerificationFailure(verification.errors);
     }
     const documents = workspaceDocuments(entries.length === 0
         ? EMPTY_CANONICAL_DOCUMENT
@@ -123,7 +145,7 @@ async function appendWorkspaceHistoryChangeLocked(change) {
     const entries = await readHistoryEntries(historyPath, WORKSPACE_HISTORY_ID);
     const verification = verifyHistoryChain(entries);
     if (!verification.ok) {
-        throw new TypeError(`Workspace history verification failed: ${verification.errors.join(", ")}`);
+        throwWorkspaceHistoryVerificationFailure(verification.errors);
     }
     const idempotentEntry = change.idempotencyKey === undefined
         ? undefined
@@ -194,7 +216,7 @@ export async function appendWorkspaceAuditEvent(options) {
         const entries = await readHistoryEntries(historyPath, WORKSPACE_HISTORY_ID);
         const verification = verifyHistoryChain(entries);
         if (!verification.ok) {
-            throw new TypeError(`Workspace history verification failed: ${verification.errors.join(", ")}`);
+            throwWorkspaceHistoryVerificationFailure(verification.errors);
         }
         const beforeDocument = entries.length === 0
             ? EMPTY_CANONICAL_DOCUMENT
@@ -303,7 +325,7 @@ export async function reconcileWorkspaceJsonHistory(options) {
         const entries = await readHistoryEntries(historyPath, WORKSPACE_HISTORY_ID);
         const verification = verifyHistoryChain(entries);
         if (!verification.ok) {
-            throw new TypeError(`Workspace history verification failed: ${verification.errors.join(", ")}`);
+            throwWorkspaceHistoryVerificationFailure(verification.errors);
         }
         const beforeDocument = replayWorkspaceEntries(entries);
         const priorDocuments = workspaceDocuments(beforeDocument);
@@ -349,15 +371,15 @@ export async function restoreWorkspaceJsonFromHistory(options) {
     try {
         const { documentPath, absolutePath } = resolveGovernedDocumentPath(options.pmRoot, options.filePath);
         const entries = await readHistoryEntries(getWorkspaceHistoryPath(options.pmRoot), WORKSPACE_HISTORY_ID);
+        const verification = verifyHistoryChain(entries);
+        if (!verification.ok) {
+            throwWorkspaceHistoryVerificationFailure(verification.errors);
+        }
         if (!Number.isInteger(options.targetVersion) ||
             options.targetVersion < 1 ||
             options.targetVersion > entries.length) {
             throw new TypeError(`Invalid workspace history target version: ${String(options.targetVersion)}`);
         }
-        const verification = verifyHistoryChain(entries);
-        if (!verification.ok) {
-            throw new TypeError(`Workspace history verification failed: ${verification.errors.join(", ")}`);
-        }
         const target = workspaceDocuments(replayWorkspaceEntries(entries, options.targetVersion))[documentPath];
         if (target === undefined) {
             throw new TypeError(`Workspace history version ${options.targetVersion} does not contain ${documentPath}`);
@@ -408,4 +430,4 @@ export async function restoreWorkspaceJsonFromHistory(options) {
     }
 }
 //# sourceMappingURL=workspace-history.js.map
-//# debugId=0f666995-78f8-5741-ae0c-0d792feea599
+//# debugId=9027d972-ce29-5511-ba81-27e17d97446e

package/dist/core/output/output.js

@@ -4,14 +4,14 @@
  * Formats compact human and machine output for Output.
  */
 
-!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]="bccd5918-1a51-5258-8d66-1960c51523cf")}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]="202cbb3e-71fe-5701-a1f5-eb515bf56561")}catch(e){}}();
 import { getActiveCommandContext, runActiveCommandOverride, runActiveRendererOverride, runActiveServiceOverrideSync, setActiveCommandResult, } from "../extensions/index.js";
 import { EXIT_CODE } from "../shared/constants.js";
 import { isHostOutputSuppressed } from "./output-control.js";
 import { projectMutationResult } from "./mutation-projection.js";
 import { attachReadOutputContracts } from "../../sdk/context-intent-contracts.js";
 import { attachOutputTokenAccounting } from "../../sdk/output-token-accounting.js";
-import { resolveReadOutputEncoding } from "../../sdk/read-output-contracts.js";
+import { isReadOutputBudgetExceeded, resolveReadOutputEncoding, } from "../../sdk/read-output-contracts.js";
 import { encode as encodeToon } from "@toon-format/toon";
 const DECLARED_PROCESS_EXIT_CODES = new Set(Object.values(EXIT_CODE));
 const NATIVE_OUTPUT_MARKER = "__pm_native_output";
@@ -389,6 +389,9 @@ function formatEffectiveOutput(effectiveResult, nativeOutput, options) {
         ? projectLinkedTestEvidence(outputResult, options.lean === true)
         : outputResult;
     const intentOutputResult = attachReadOutputContracts(command, resolvedCommandOptions, projectedOutputResult);
+    if (isReadOutputBudgetExceeded(intentOutputResult)) {
+        process.exitCode ||= EXIT_CODE.USAGE;
+    }
     const renderResolvedOutput = (value) => {
         if (format === "toon") {
             const markdownDefault = renderDefaultMarkdownResult(value);
@@ -465,4 +468,4 @@ export const outputTestOnly = {
     renderToonValue,
 };
 //# sourceMappingURL=output.js.map
-//# debugId=bccd5918-1a51-5258-8d66-1960c51523cf
+//# debugId=202cbb3e-71fe-5701-a1f5-eb515bf56561

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 {