@victframework/runtime 0.1.0

package/dist/control-types.js

@@ -0,0 +1,779 @@
+import { createHash } from 'node:crypto';
+import { validateAgentStreamEvent, } from '@victframework/contracts';
+import { toCanonicalJson } from './serialization.js';
+/**
+ * Stage 06B — neutral control-plane and governed-remote-execution ports.
+ *
+ * This module defines the durable records, closed state machines, and store
+ * ports for:
+ *
+ * - authenticated actors, roles, and scopes (SEC-001/SEC-002; default deny);
+ * - ChangeSets with immutable content identity, evidence, approvals,
+ *   expiry, and forward-only status (CTRL-001..CTRL-007);
+ * - Application Release publish/select/rollback over immutable versions;
+ * - audit events for every attributable transition;
+ * - durable agent turns, tool invocations (durable-before-invocation), and
+ *   VICT-authoritative approval records (AI-006/AI-007/MSTR-005);
+ * - the durable agent-stream ledger (per-stream monotonic sequences,
+ *   durable milestones, transient deltas — AI-009, `vict.agent-stream@1`).
+ *
+ * In-memory reference implementations live in `control-in-memory.ts`; the
+ * SQLite adapter implements the same ports in `@victframework/store-sqlite` and both
+ * pass the shared conformance suite (`control-conformance.ts`).
+ *
+ * These are NEUTRAL ports: no Mastra, HTTP, transport, or provider type
+ * appears here.
+ */
+// ---- Identifier and hashing primitives -------------------------------------
+/** Bounded namespace identifier for control-plane and agent records. */
+export const CONTROL_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:@-]{0,127}$/;
+/** Validate one bounded namespace identifier (throws a stable error). */
+export function assertControlId(value, field) {
+    if (typeof value !== 'string' || !CONTROL_ID_PATTERN.test(value)) {
+        throw new VictControlError('VICT_CONTROL_ID_INVALID', `${field} must be a bounded namespace identifier (at most 128 characters; letters, digits, '.', '_', ':', '@', '-').`);
+    }
+}
+/** Stable bounded safe-integer validation. */
+export function assertControlTimestamp(value, field) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0) {
+        throw new VictControlError('VICT_CONTROL_TIMESTAMP_INVALID', `${field} must be a finite epoch-ms integer.`);
+    }
+}
+/**
+ * Stable content identity over strict canonical data. The canonicalizer is
+ * the Stage 01 verified canonical JSON; identity MUST NOT be derived from
+ * function text, timestamps of capture, or mutable objects.
+ */
+export function controlContentHash(payload) {
+    // A versioned prefix keeps content identities domain-scoped.
+    return `v1_${sha256Hex(`vict.control-content@1\u0000${toCanonicalJson(payload)}`)}`;
+}
+/** Bounded safe string field (rationales, summaries, reason codes). */
+export function assertBoundedString(value, field, max, allowEmpty = false) {
+    if (typeof value !== 'string' ||
+        (value.length === 0 && !allowEmpty) ||
+        value.length > max ||
+        // Control characters and other unsafe content are rejected; the value
+        // itself is never echoed into diagnostics.
+        // eslint-disable-next-line no-control-regex
+        /[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/.test(value)) {
+        throw new Error(`VICT_CONTROL_FIELD_INVALID: ${field} must be a bounded string of at most ${max} characters without control characters.`);
+    }
+}
+function sha256Hex(payload) {
+    return createHash('sha256').update(payload, 'utf8').digest('hex');
+}
+// ---- Actors, roles, and scopes ---------------------------------------------
+/** The closed reference role vocabulary (system reference §14.2). */
+export const ACTOR_ROLES = [
+    'viewer',
+    'developer',
+    'operator',
+    'approver',
+    'administrator',
+];
+/** The closed scope vocabulary enforced below the HTTP/CLI/UI layers. */
+export const ACTOR_SCOPES = [
+    'changeset.propose',
+    'changeset.revise',
+    'changeset.approve',
+    'changeset.commit',
+    'changeset.read',
+    'release.publish',
+    'release.select',
+    'release.read',
+    'activation.select',
+    'activation.read',
+    'run.read',
+    'run.cancel',
+    'operator.resolve',
+    'agent.turn.start',
+    'agent.turn.cancel',
+    'agent.tool.approve',
+    'agent.tool.decline',
+    'agent.stream.read',
+    'app.data.read',
+    'app.data.write',
+    'conversation.read',
+    'conversation.delete',
+    'audit.read',
+];
+/** Deterministic role → scope policy (default policy is denial). */
+export const ROLE_SCOPES = {
+    viewer: ['changeset.read', 'release.read', 'activation.read', 'run.read', 'audit.read'],
+    developer: [
+        'changeset.read',
+        'changeset.propose',
+        'changeset.revise',
+        'release.read',
+        'activation.read',
+        'run.read',
+        'agent.turn.start',
+        'agent.turn.cancel',
+        'agent.stream.read',
+        'app.data.read',
+        'audit.read',
+    ],
+    operator: [
+        'changeset.read',
+        'release.read',
+        'release.select',
+        'activation.read',
+        'activation.select',
+        'run.read',
+        'run.cancel',
+        'operator.resolve',
+        'agent.turn.cancel',
+        'agent.stream.read',
+        'app.data.read',
+        'app.data.write',
+        'conversation.read',
+        'conversation.delete',
+        'audit.read',
+    ],
+    approver: [
+        'changeset.read',
+        'changeset.approve',
+        'agent.tool.approve',
+        'agent.tool.decline',
+        'release.read',
+        'activation.read',
+        'run.read',
+        'audit.read',
+    ],
+    administrator: [...ACTOR_SCOPES],
+};
+/**
+ * Derive the permitted scopes of one actor record. Unknown, disabled, and
+ * malformed actors fail closed: no scopes are derived. Roles outside the
+ * closed vocabulary are ignored (fail closed, never widened).
+ */
+export function authoritativeScopes(actor) {
+    if (actor === undefined || actor.status !== 'active') {
+        return [];
+    }
+    const scopes = new Set();
+    for (const role of actor.roles) {
+        if (!ACTOR_ROLES.includes(role)) {
+            continue;
+        }
+        for (const scope of ROLE_SCOPES[role]) {
+            scopes.add(scope);
+        }
+    }
+    return [...scopes].sort();
+}
+/**
+ * Derive the authoritative server context from a resolved actor record.
+ * Unknown, disabled, malformed, or mismatched actors fail closed.
+ */
+export function authenticatedActorContext(actor, requestedActorId) {
+    // Mismatch between the authenticated identity and any requested actor id
+    // is denied: the authenticated record is the only authority.
+    if (actor === undefined || actor.status !== 'active' || actor.actorId !== requestedActorId) {
+        throw new VictControlError('VICT_ACTOR_UNAUTHENTICATED', 'VICT_ACTOR_UNAUTHENTICATED: the actor could not be authenticated.');
+    }
+    assertControlId(actor.actorId, 'actorId');
+    return {
+        actorId: actor.actorId,
+        roles: [...actor.roles],
+        scopes: authoritativeScopes(actor),
+        mastraResourceId: `vict-actor-${actor.actorId}`,
+    };
+}
+/** Stable authorization denial (never echoes the attempted operation's payload). */
+export class ActorScopeDeniedError extends Error {
+    code = 'VICT_ACTOR_SCOPE_DENIED';
+    scope;
+    constructor(scope) {
+        super(`VICT_ACTOR_SCOPE_DENIED: the authenticated actor does not hold the '${scope}' scope.`);
+        this.name = 'ActorScopeDeniedError';
+        this.scope = scope;
+    }
+}
+/** Enforce one scope (fail closed; stable non-echoing denial). */
+export function assertActorScope(context, scope) {
+    if (!context.scopes.includes(scope)) {
+        throw new ActorScopeDeniedError(scope);
+    }
+}
+/** In-memory ActorDirectory (tests and local compositions). */
+export class InMemoryActorDirectory {
+    #actors = new Map();
+    async get(actorId) {
+        const record = this.#actors.get(actorId);
+        return record === undefined ? undefined : { ...record, roles: [...record.roles] };
+    }
+    async list() {
+        return [...this.#actors.values()]
+            .sort((a, b) => (a.actorId < b.actorId ? -1 : 1))
+            .map((record) => ({ ...record, roles: [...record.roles] }));
+    }
+    async upsert(record) {
+        assertControlId(record.actorId, 'actorId');
+        if (record.status !== 'active' && record.status !== 'disabled') {
+            throw new VictControlError('VICT_CONTROL_FIELD_INVALID', 'actor status must be active or disabled.');
+        }
+        if (!Array.isArray(record.roles)) {
+            throw new VictControlError('VICT_CONTROL_FIELD_INVALID', 'actor roles must be an array.');
+        }
+        for (const role of record.roles) {
+            if (!ACTOR_ROLES.includes(role)) {
+                throw new VictControlError('VICT_CONTROL_FIELD_INVALID', 'actor roles must use the closed role vocabulary.');
+            }
+        }
+        assertControlTimestamp(record.createdAt, 'actor.createdAt');
+        this.#actors.set(record.actorId, { ...record, roles: [...record.roles] });
+    }
+}
+// ---- ChangeSets --------------------------------------------------------------
+/** The versioned ChangeSet schema marker. */
+export const CHANGESET_SCHEMA = 'vict.changeset@1';
+/** The sentinel base version meaning 'no version is currently selected'. */
+export const CHANGESET_BASE_NONE = 'none';
+/** Derive the stable operation identity for one ChangeSet operation. */
+export function changeSetOperationIdentity(input) {
+    return controlContentHash({
+        domain: 'vict.changeset-operation@1',
+        changesetId: input.changesetId,
+        contentHash: input.contentHash,
+        operationIndex: input.operationIndex,
+        operation: input.operation,
+    });
+}
+/**
+ * The CLOSED structural vocabulary of one ChangeSet operation kind: every
+ * kind declares its EXACT required own members. A declaration that misses
+ * a member, adds a member, or mistypes a member is malformed and can
+ * never reach a content hash or a durable record.
+ */
+const CHANGESET_OPERATION_FIELDS = {
+    'select-activation': ['kind', 'graphId', 'activationVersion'],
+    'rollback-activation': ['kind', 'graphId', 'targetActivationVersion'],
+    'publish-and-select-release': ['kind', 'release'],
+    'select-release': ['kind', 'applicationId', 'releaseVersion'],
+    'rollback-release': ['kind', 'applicationId', 'targetReleaseVersion'],
+};
+/**
+ * The exact declared members of the ChangeSet base (closed structure).
+ */
+const CHANGESET_BASE_FIELDS = ['kind', 'subjectId', 'expectedVersion'];
+/**
+ * Capture a CLOSED plain-data record without ever invoking caller code or
+ * echoing captured values:
+ *
+ * - the value must be a non-null, non-array object whose prototype is
+ *   exactly `Object.prototype` (or null) — class instances, exotic
+ *   prototypes, and structs smuggled through exotic prototypes fail;
+ * - property enumeration, `Reflect.ownKeys`, and descriptor reads are
+ *   guarded — a hostile proxy that throws is rejected without a raw
+ *   exception crossing the boundary;
+ * - OWN string-keyed ENUMERABLE data properties only: accessors
+ *   (getters/setters), inherited members, non-enumerable fields, and
+ *   symbol keys are rejected, and getters are NEVER invoked (values are
+ *   read exclusively through the captured property descriptor).
+ * - the field set must be EXACTLY the declared closed set.
+ *
+ * The returned capture is a freshly allocated plain object owned by VICT
+ * (the caller's object is never retained, frozen, or mutated).
+ */
+export function captureClosedControlRecord(raw, field, allowed) {
+    // Every inspection primitive — including `Array.isArray`, which THROWS on
+    // a revoked Proxy — is guarded: no raw exception ever crosses the boundary.
+    let arrayLike;
+    try {
+        arrayLike = Array.isArray(raw);
+    }
+    catch {
+        throw new VictControlError('VICT_CONTROL_STRUCTURE_INVALID', `The ${field} could not be inspected; hostile containers are rejected.`);
+    }
+    if (typeof raw !== 'object' || raw === null || arrayLike) {
+        throw new VictControlError('VICT_CONTROL_STRUCTURE_INVALID', `The ${field} must be a plain object with a closed field set.`);
+    }
+    let prototype;
+    try {
+        prototype = Object.getPrototypeOf(raw);
+    }
+    catch {
+        throw new VictControlError('VICT_CONTROL_STRUCTURE_INVALID', `The ${field} could not be inspected; hostile containers are rejected.`);
+    }
+    if (prototype !== Object.prototype && prototype !== null) {
+        throw new VictControlError('VICT_CONTROL_STRUCTURE_INVALID', `The ${field} must be a plain data record; exotic prototypes are rejected.`);
+    }
+    let ownKeys;
+    try {
+        ownKeys = Reflect.ownKeys(raw);
+    }
+    catch {
+        throw new VictControlError('VICT_CONTROL_STRUCTURE_INVALID', `The ${field} could not be enumerated; hostile containers are rejected.`);
+    }
+    const capture = {};
+    for (const key of ownKeys) {
+        if (typeof key !== 'string') {
+            throw new VictControlError('VICT_CONTROL_STRUCTURE_INVALID', `The ${field} declares a symbol key; only plain data properties are accepted.`);
+        }
+        if (allowed !== undefined && !allowed.includes(key)) {
+            throw new VictControlError('VICT_CONTROL_STRUCTURE_INVALID', `The ${field} declares a field outside the closed structure.`);
+        }
+        let descriptor;
+        try {
+            descriptor = Object.getOwnPropertyDescriptor(raw, key);
+        }
+        catch {
+            throw new VictControlError('VICT_CONTROL_STRUCTURE_INVALID', `The ${field} could not be inspected; hostile containers are rejected.`);
+        }
+        if (descriptor === undefined ||
+            descriptor.get !== undefined ||
+            descriptor.set !== undefined ||
+            descriptor.enumerable !== true) {
+            throw new VictControlError('VICT_CONTROL_STRUCTURE_INVALID', `The ${field} declares an accessor, inherited, or non-enumerable member; only own enumerable data properties are accepted.`);
+        }
+        capture[key] = descriptor.value;
+    }
+    for (const required of allowed ?? []) {
+        if (!(required in capture)) {
+            throw new VictControlError('VICT_CONTROL_STRUCTURE_INVALID', `The ${field} is missing a required member of the closed structure.`);
+        }
+    }
+    return capture;
+}
+/**
+ * Capture a CLOSED dense array without ever invoking caller code:
+ *
+ * - the value must be a REAL array (`Array.isArray` under a guard — a
+ *   revoked Proxy throws there — whose prototype is exactly
+ *   `Array.prototype`);
+ * - the `length` is read through its OWN DESCRIPTOR under a guard (never a
+ *   `get`, which would be a caller-controlled trap): it must be an own
+ *   DATA property carrying a safe integer within [1, maxLength];
+ * - `Reflect.ownKeys` (guarded) must declare EXACTLY the length and the
+ *   dense index keys: extra string or symbol properties, sparse holes,
+ *   non-enumerable indices, accessors, and hostile enumeration/descriptor
+ *   traps are ALL rejected;
+ * - elements are captured exclusively through their guarded own property
+ *   DESCRIPTORS (enumerable data properties only) — caller `.map()`,
+ *   iterators, getters, and index `get` traps are never consulted.
+ *
+ * The returned array is freshly allocated and owned by VICT (the caller's
+ * array is never retained, frozen, or aliased).
+ */
+export function captureClosedControlArray(raw, field, maxLength) {
+    let arrayLike;
+    try {
+        arrayLike = Array.isArray(raw);
+    }
+    catch {
+        throw new VictControlError('VICT_CONTROL_STRUCTURE_INVALID', `The ${field} could not be inspected; hostile containers are rejected.`);
+    }
+    if (!arrayLike) {
+        throw new VictControlError('VICT_CONTROL_STRUCTURE_INVALID', `The ${field} must be an array with a closed dense structure.`);
+    }
+    let prototype;
+    try {
+        prototype = Object.getPrototypeOf(raw);
+    }
+    catch {
+        throw new VictControlError('VICT_CONTROL_STRUCTURE_INVALID', `The ${field} could not be inspected; hostile containers are rejected.`);
+    }
+    if (prototype !== Array.prototype) {
+        throw new VictControlError('VICT_CONTROL_STRUCTURE_INVALID', `The ${field} must be a plain array; exotic prototypes are rejected.`);
+    }
+    // The length is inspected through its guarded own DESCRIPTOR — never a
+    // caller-controlled `get`.
+    let lengthDescriptor;
+    try {
+        lengthDescriptor = Object.getOwnPropertyDescriptor(raw, 'length');
+    }
+    catch {
+        throw new VictControlError('VICT_CONTROL_STRUCTURE_INVALID', `The ${field} could not be inspected; hostile containers are rejected.`);
+    }
+    if (lengthDescriptor === undefined ||
+        lengthDescriptor.get !== undefined ||
+        lengthDescriptor.set !== undefined ||
+        typeof lengthDescriptor.value !== 'number' ||
+        !Number.isSafeInteger(lengthDescriptor.value) ||
+        lengthDescriptor.value < 1 ||
+        lengthDescriptor.value > maxLength) {
+        throw new VictControlError('VICT_CONTROL_STRUCTURE_INVALID', `The ${field} length is outside the closed bounded structure.`);
+    }
+    const length = lengthDescriptor.value;
+    // The declared key set must be EXACTLY the dense index set plus length.
+    let ownKeys;
+    try {
+        ownKeys = Reflect.ownKeys(raw);
+    }
+    catch {
+        throw new VictControlError('VICT_CONTROL_STRUCTURE_INVALID', `The ${field} could not be enumerated; hostile containers are rejected.`);
+    }
+    const expectedKeys = new Set(['length']);
+    for (let index = 0; index < length; index += 1) {
+        expectedKeys.add(String(index));
+    }
+    if (ownKeys.length !== expectedKeys.size) {
+        throw new VictControlError('VICT_CONTROL_STRUCTURE_INVALID', `The ${field} declares members outside the closed dense structure.`);
+    }
+    for (const key of ownKeys) {
+        if (!expectedKeys.has(key)) {
+            throw new VictControlError('VICT_CONTROL_STRUCTURE_INVALID', `The ${field} declares a member outside the closed dense structure.`);
+        }
+    }
+    // Dense capture: every index must be an OWN ENUMERABLE DATA property read
+    // through its guarded descriptor (accessors, holes, and non-enumerable
+    // indices are rejected; caller getters are never invoked).
+    const capture = new Array(length);
+    for (let index = 0; index < length; index += 1) {
+        let descriptor;
+        try {
+            descriptor = Object.getOwnPropertyDescriptor(raw, String(index));
+        }
+        catch {
+            throw new VictControlError('VICT_CONTROL_STRUCTURE_INVALID', `The ${field} could not be inspected; hostile containers are rejected.`);
+        }
+        if (descriptor === undefined ||
+            descriptor.get !== undefined ||
+            descriptor.set !== undefined ||
+            descriptor.enumerable !== true) {
+            throw new VictControlError('VICT_CONTROL_STRUCTURE_INVALID', `The ${field} must be a dense array of own enumerable data elements.`);
+        }
+        capture[index] = descriptor.value;
+    }
+    return capture;
+}
+/** Validate a required bounded string identifier member (exact type). */
+function requireBoundedMember(capture, field) {
+    const value = capture[field];
+    if (typeof value !== 'string') {
+        throw new VictControlError('VICT_CONTROL_FIELD_INVALID', `The member '${field}' must be a string.`);
+    }
+    assertControlId(value, field);
+    return value;
+}
+/**
+ * Validate the structural shape of one ChangeSet operation (fail closed).
+ *
+ * EVERY required member of the operation kind is enforced with its exact
+ * runtime type, non-empty bounded identifier form, and the closed own-field
+ * set. Accessors, inherited/non-enumerable members, symbols, exotic
+ * prototypes, and hostile proxies are rejected WITHOUT invoking getters or
+ * echoing captured values. Only the validated VICT-owned canonical capture
+ * is returned/hashed — never the original caller object.
+ */
+export function validateChangeSetOperation(operation) {
+    // Structural capture FIRST (closed plain-data discipline, no field-set
+    // restriction yet) to read the kind identity WITHOUT invoking getters.
+    const structure = captureClosedControlRecord(operation, 'ChangeSet operation', undefined);
+    if (typeof structure.kind !== 'string' || !(structure.kind in CHANGESET_OPERATION_FIELDS)) {
+        throw new VictControlError('VICT_CONTROL_OPERATION_INVALID', 'The ChangeSet operation kind is outside the closed vocabulary.');
+    }
+    const kindCapture = structure.kind;
+    const allowed = CHANGESET_OPERATION_FIELDS[kindCapture];
+    // Re-capture with the EXACT closed field set for the resolved kind.
+    const capture = captureClosedControlRecord(operation, 'ChangeSet operation', allowed);
+    if (capture.kind !== kindCapture) {
+        throw new VictControlError('VICT_CONTROL_OPERATION_INVALID', 'The ChangeSet operation kind must be a stable string identity.');
+    }
+    switch (kindCapture) {
+        case 'select-activation':
+            return {
+                kind: 'select-activation',
+                graphId: requireBoundedMember(capture, 'graphId'),
+                activationVersion: requireBoundedMember(capture, 'activationVersion'),
+            };
+        case 'rollback-activation':
+            return {
+                kind: 'rollback-activation',
+                graphId: requireBoundedMember(capture, 'graphId'),
+                targetActivationVersion: requireBoundedMember(capture, 'targetActivationVersion'),
+            };
+        case 'publish-and-select-release':
+            return {
+                kind: 'publish-and-select-release',
+                release: validateApplicationReleaseContent(capture.release),
+            };
+        case 'select-release':
+            return {
+                kind: 'select-release',
+                applicationId: requireBoundedMember(capture, 'applicationId'),
+                releaseVersion: requireBoundedMember(capture, 'releaseVersion'),
+            };
+        case 'rollback-release':
+            return {
+                kind: 'rollback-release',
+                applicationId: requireBoundedMember(capture, 'applicationId'),
+                targetReleaseVersion: requireBoundedMember(capture, 'targetReleaseVersion'),
+            };
+        default:
+            throw new VictControlError('VICT_CONTROL_OPERATION_INVALID', 'The ChangeSet operation kind is outside the closed vocabulary.');
+    }
+}
+/** The closed immutable release content fields. */
+const RELEASE_CONTENT_FIELDS = [
+    'releaseVersion',
+    'applicationId',
+    'applicationVersion',
+    'rendererIdentity',
+    'componentRegistryIdentity',
+    'dataAdapterIdentity',
+    'activationBinding',
+];
+/**
+ * Validate one immutable Application Release content record (fail closed).
+ * The content is captured as a CLOSED plain-data structure (exact member
+ * set, exact string types, no accessors/symbols/hostile containers) and
+ * the returned record is a fresh VICT-owned capture.
+ */
+export function validateApplicationReleaseContent(content) {
+    const capture = captureClosedControlRecord(content, 'release content', RELEASE_CONTENT_FIELDS);
+    for (const field of RELEASE_CONTENT_FIELDS) {
+        const value = capture[field];
+        if (typeof value !== 'string') {
+            throw new VictControlError('VICT_CONTROL_RELEASE_INVALID', `The release member '${field}' must be a string.`);
+        }
+        assertControlId(value, `release.${field}`);
+    }
+    return {
+        releaseVersion: capture.releaseVersion,
+        applicationId: capture.applicationId,
+        applicationVersion: capture.applicationVersion,
+        rendererIdentity: capture.rendererIdentity,
+        componentRegistryIdentity: capture.componentRegistryIdentity,
+        dataAdapterIdentity: capture.dataAdapterIdentity,
+        activationBinding: capture.activationBinding,
+    };
+}
+/** The exact declared members of the ChangeSet authoring input envelope. */
+const CHANGESET_CONTENT_INPUT_FIELDS = [
+    'changesetId',
+    'authorActorId',
+    'createdAt',
+    'base',
+    'operations',
+    'rationale',
+    'riskClass',
+    'requiredApproverCount',
+    'expiresAt',
+];
+/** Validate a full ChangeSet authoring input and derive its content hash.
+ *
+ * The COMPLETE untrusted runtime input is CAPTURED at this boundary before
+ * any member is read: the outer envelope must be a plain object with the
+ * EXACT closed field set, and `base`, the operation list, and every
+ * operation are captured through guarded descriptors (no caller getter,
+ * iterator, `.map()`, or other caller-controlled behavior is ever
+ * consulted; hostile/revoked proxies, sparse arrays, accessors, symbols,
+ * non-enumerable members, and exotic prototypes are all rejected with ONE
+ * stable, non-echoing error). Only VICT-owned validated captures are
+ * hashed and returned; caller objects are never retained, frozen, or aliased.
+ */
+export function validateChangeSetContent(untrustedInput) {
+    // ---- 1. CAPTURE the complete outer envelope (closed field set) BEFORE
+    // any semantic inspection. Scalar members are captured by descriptor
+    // value too, so caller getters never run (a getter on ANY outer field —
+    // not only `base` — is rejected without being invoked).
+    const input = captureClosedControlRecord(untrustedInput, 'ChangeSet authoring input', CHANGESET_CONTENT_INPUT_FIELDS);
+    if (typeof input.changesetId !== 'string') {
+        throw new VictControlError('VICT_CONTROL_FIELD_INVALID', 'the ChangeSet id is malformed.');
+    }
+    if (typeof input.authorActorId !== 'string') {
+        throw new VictControlError('VICT_CONTROL_FIELD_INVALID', 'the ChangeSet author is malformed.');
+    }
+    if (typeof input.createdAt !== 'number' ||
+        !Number.isSafeInteger(input.createdAt) ||
+        typeof input.expiresAt !== 'number' ||
+        !Number.isSafeInteger(input.expiresAt)) {
+        throw new VictControlError('VICT_CONTROL_FIELD_INVALID', 'the ChangeSet timestamps are malformed.');
+    }
+    assertControlId(input.changesetId, 'changesetId');
+    assertControlId(input.authorActorId, 'authorActorId');
+    assertControlTimestamp(input.createdAt, 'createdAt');
+    assertControlTimestamp(input.expiresAt, 'expiresAt');
+    if (input.expiresAt <= input.createdAt) {
+        throw new VictControlError('VICT_CONTROL_FIELD_INVALID', 'a ChangeSet must expire after its creation.');
+    }
+    // ---- 2. The base is CAPTURED (closed plain-data structure: exactly its
+    // declared members, exact string types, no accessors/symbols/hostile
+    // containers) before semantic inspection — a hostile `base.kind` getter
+    // is never invoked and a revoked proxy never escapes a raw TypeError.
+    const baseCapture = captureClosedControlRecord(input.base, 'ChangeSet base', CHANGESET_BASE_FIELDS);
+    if (baseCapture.kind !== 'activation' && baseCapture.kind !== 'release') {
+        throw new VictControlError('VICT_CONTROL_FIELD_INVALID', 'the ChangeSet base is malformed.');
+    }
+    if (typeof baseCapture.subjectId !== 'string' ||
+        typeof baseCapture.expectedVersion !== 'string') {
+        throw new VictControlError('VICT_CONTROL_FIELD_INVALID', 'the ChangeSet base is malformed.');
+    }
+    assertControlId(baseCapture.subjectId, 'base.subjectId');
+    assertControlId(baseCapture.expectedVersion, 'base.expectedVersion');
+    const base = {
+        kind: baseCapture.kind,
+        subjectId: baseCapture.subjectId,
+        expectedVersion: baseCapture.expectedVersion,
+    };
+    // ---- 3. The operation list is CAPTURED as a closed dense array through
+    // guarded descriptors (never caller `.map()`/iterators); sparse arrays,
+    // extra/symbol properties, accessor or non-enumerable indices, exotic
+    // prototypes, and revoked/hostile proxies all fail with ONE stable error.
+    const operationsCapture = captureClosedControlArray(input.operations, 'ChangeSet operation list', 64);
+    const operations = [];
+    for (const operation of operationsCapture) {
+        operations.push(validateChangeSetOperation(operation));
+    }
+    if (typeof input.rationale !== 'string') {
+        throw new VictControlError('VICT_CONTROL_FIELD_INVALID', 'the rationale is malformed.');
+    }
+    assertBoundedString(input.rationale, 'rationale', 2000);
+    if (input.riskClass !== 'low' && input.riskClass !== 'medium' && input.riskClass !== 'high') {
+        throw new VictControlError('VICT_CONTROL_FIELD_INVALID', 'riskClass must be low, medium, or high.');
+    }
+    if (typeof input.requiredApproverCount !== 'number' ||
+        !Number.isSafeInteger(input.requiredApproverCount) ||
+        input.requiredApproverCount < 1 ||
+        input.requiredApproverCount > 8) {
+        throw new VictControlError('VICT_CONTROL_FIELD_INVALID', 'requiredApproverCount must be a safe integer between 1 and 8.');
+    }
+    // The content identity is derived from the VALIDATED VICT-owned captures
+    // (the closed base structure and the canonical operation set) — never from
+    // the original caller objects (which could carry accessors, symbols, or
+    // exotic prototypes and are never retained).
+    const contentHash = controlContentHash({
+        schema: CHANGESET_SCHEMA,
+        authorActorId: input.authorActorId,
+        base,
+        operations,
+        rationale: input.rationale,
+        riskClass: input.riskClass,
+        requiredApproverCount: input.requiredApproverCount,
+        expiresAt: input.expiresAt,
+    });
+    return {
+        changesetId: input.changesetId,
+        base,
+        operations,
+        rationale: input.rationale,
+        riskClass: input.riskClass,
+        requiredApproverCount: input.requiredApproverCount,
+        expiresAt: input.expiresAt,
+        contentHash,
+    };
+}
+void undefined;
+/** The closed audit action vocabulary. */
+export const CONTROL_AUDIT_ACTIONS = [
+    'changeset.proposed',
+    'changeset.revised',
+    'changeset.evidence-attached',
+    'changeset.approved',
+    'changeset.declined',
+    'changeset.committed',
+    'changeset.expired',
+    'release.published',
+    'release.selected',
+    'release.rolled-back',
+    'activation.selected',
+    'activation.rolled-back',
+    'actor.recorded',
+    'run.cancelled',
+    'turn.cancelled',
+    'approval.decided',
+    'approval.expired',
+    'operator.intervened',
+];
+// ---- Agent turns ------------------------------------------------------------
+export const AGENT_TURN_SCHEMA = 'vict.agent-turn@1';
+/** Durable kinds that a ledger row persists (transient kinds never persist). */
+export function isDurableStreamKind(kind) {
+    return kind !== 'text.delta';
+}
+// ---- The composed control-plane store set -------------------------------------
+// ---- Durable command idempotency -----------------------------------------
+/** The closed, bounded idempotency-key format (HTTP + CLI surface). */
+export const COMMAND_IDEMPOTENCY_KEY_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+/** Stable structured conflict code thrown when a settlement fence mismatches. */
+export const VICT_IDEMPOTENCY_FENCE_CONFLICT = 'VICT_IDEMPOTENCY_FENCE_CONFLICT';
+/**
+ * Derive the deterministic settlement fence token for one claim
+ * generation. The token binds the namespace, the lease owner, and the
+ * attempt generation: a lease takeover always produces a NEW token, so a
+ * stale owner can never settle a claim it no longer owns.
+ */
+export function commandIdempotencyFenceToken(input) {
+    return ('vict-fence-' +
+        createHash('sha256')
+            .update(`${input.actorId}\u0000${input.command}\u0000${input.idempotencyKey}\u0000${input.owner}\u0000${input.attempts}`, 'utf8')
+            .digest('hex'));
+}
+/** Validation error for any control-plane structural violation. */
+export class VictControlError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'VictControlError';
+        this.code = code;
+    }
+}
+/** Canonical JSON of one stream event's safe payload fields (context minus stream identity). */
+export function streamEventPayloadOf(event) {
+    const payload = {};
+    for (const [key, value] of Object.entries(event)) {
+        if (key === 'streamId' || key === 'seq' || key === 'createdAt') {
+            continue;
+        }
+        payload[key] = value;
+    }
+    return toCanonicalJson(payload);
+}
+// ---- The stream-ledger append gate (store-boundary schema enforcement) ------
+/**
+ * Validate ONE append against the final `vict.agent-stream@1` schema at
+ * the STORE boundary — before any sequence state is incremented or any
+ * storage mutated. The RAW ledger ports are the last line of defense:
+ * plain-JavaScript callers cannot bypass the schema through them.
+ *
+ * Enforced here:
+ * - the payload is a JSON object in CANONICAL form (non-canonical JSON is
+ *   rejected, not silently re-serialized);
+ * - the declared kind is inside the closed vocabulary and matches the
+ *   payload's `kind` member;
+ * - the reconstructed event (payload + stream identity + the sequence that
+ *   WOULD be assigned) passes the complete field-level schema (unknown
+ *   kinds/fields, malformed correlation IDs, unsafe codes, raw text in
+ *   `content.completed`, invalid usage — all fail closed).
+ *
+ * Errors are stable and non-echoing: `VICT_STREAM_EVENT_INVALID` carries
+ * schema issue CODES only, never the rejected values.
+ */
+export function validateStreamLedgerAppend(command) {
+    assertControlId(command.streamId, 'streamId');
+    let parsed;
+    try {
+        parsed = JSON.parse(command.payload);
+    }
+    catch {
+        throw new VictControlError('VICT_STREAM_EVENT_INVALID', 'The stream event payload is not valid JSON; the ledger rejects it without persisting anything.');
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new VictControlError('VICT_STREAM_EVENT_INVALID', 'The stream event payload must be a JSON object.');
+    }
+    // Canonical-form enforcement: the stored payload must be the canonical
+    // serialization of its own content (no key-order drift, no whitespace).
+    if (toCanonicalJson(parsed) !== command.payload) {
+        throw new VictControlError('VICT_STREAM_EVENT_INVALID', 'The stream event payload is not canonical JSON; persisting it would break byte-stable replay.');
+    }
+    const candidate = parsed;
+    if (candidate['kind'] !== command.kind) {
+        throw new VictControlError('VICT_STREAM_EVENT_INVALID', 'The payload kind does not match the declared event kind.');
+    }
+    const event = {
+        ...candidate,
+        streamId: command.streamId,
+        seq: command.assignedSeq,
+    };
+    const validation = validateAgentStreamEvent(event);
+    if (!validation.ok) {
+        throw new VictControlError('VICT_STREAM_EVENT_INVALID', `The event is not a valid vict.agent-stream@1 event (${validation.issues
+            .map((issue) => issue.code)
+            .join(', ')}).`);
+    }
+    return event;
+}
+//# sourceMappingURL=control-types.js.map