@blokjs/shared 2.1.0 → 2.2.1

package/dist/PolicyContracts.d.ts

@@ -0,0 +1,184 @@
+import type { CapabilityEffect, CapabilityManifestV1 } from "./CapabilityManifest.js";
+import type { ApprovalContract } from "./EnforcementContracts.js";
+import type { CapabilityAuthority } from "./PermissionAlgebra.js";
+export type ExecutionOrigin = "ordinary" | "agent";
+export interface PrincipalIdentity {
+    readonly id: string;
+    readonly kind: string;
+}
+export interface SessionIdentity {
+    readonly id: string;
+}
+export interface TurnIdentity {
+    readonly id: string;
+    readonly index?: number;
+}
+/**
+ * Bounded lineage for policy and interaction records.
+ *
+ * The runner may execute a policy request from a nested workflow or a
+ * parallel branch. Keeping this metadata on the request means a control-plane
+ * consumer can attribute an answer without inferring ownership from a step
+ * name (which is only unique within one workflow definition).
+ */
+export interface InteractionAttribution {
+    /** Stable root execution/session lineage identifier. */
+    readonly rootId: string;
+    /** Parent run, workflow, or interaction identifier when nested. */
+    readonly parentId?: string;
+    /** Stable branch/child identifier for parallel or delegated work. */
+    readonly branchId?: string;
+    /** Zero-based branch position, when the parent fan-out has an index. */
+    readonly branchIndex?: number;
+    /** Ordered, bounded path of nested workflow/branch labels. */
+    readonly branchPath?: readonly string[];
+    /** Nesting depth; root executions use zero. */
+    readonly depth: number;
+}
+export interface WorkflowIdentity {
+    readonly name: string;
+    readonly version?: string;
+}
+export interface StepIdentity {
+    readonly id: string;
+    readonly index?: number;
+    readonly attempt?: number;
+}
+/** Scope requested by a node or policy provider; structurally an authority envelope. */
+export type RequestedCapabilityScope = CapabilityAuthority;
+export type PolicyLayerName = "deployment" | "repository" | "workflow" | "phase" | "user";
+export interface PolicyLayer {
+    readonly name: PolicyLayerName;
+    readonly version: string;
+}
+export interface PolicyRuleMatch {
+    readonly layer: PolicyLayerName;
+    readonly ruleId: string;
+    readonly effect?: "allow" | "deny" | "ask" | "require-sandbox";
+}
+export type PolicyDecisionKind = "allow" | "deny" | "ask" | "require-sandbox";
+export interface PolicyDecision {
+    readonly kind: PolicyDecisionKind;
+    readonly id: string;
+    readonly reasonCode: string;
+    readonly reason?: string;
+    readonly policyVersion: string;
+}
+export interface SandboxAttestation {
+    readonly id: string;
+    readonly issuedAt: string;
+    readonly expiresAt: string;
+    readonly principalId: string;
+    readonly sessionId: string;
+    readonly workflow: WorkflowIdentity;
+    readonly step: StepIdentity;
+    readonly effects: readonly CapabilityEffect[];
+    readonly profile: string;
+    readonly policyDecisionId: string;
+    readonly proof: string;
+}
+export interface PolicyContext {
+    readonly origin: ExecutionOrigin;
+    readonly principal?: PrincipalIdentity;
+    readonly session?: SessionIdentity;
+    readonly turn?: TurnIdentity;
+    readonly attribution?: InteractionAttribution;
+    readonly workflow: WorkflowIdentity;
+    readonly step: StepIdentity;
+    readonly manifest: CapabilityManifestV1 | null;
+    readonly scope: RequestedCapabilityScope;
+    readonly layers: readonly PolicyLayer[];
+    readonly signal?: AbortSignal;
+    /** Explicit approval handoff requested by an H1-02 approval step. */
+    readonly approval?: ApprovalContract;
+}
+export interface PolicyRequest extends PolicyContext {
+    readonly requestId: string;
+    /** Durable execution reference when this request is an interaction ask. */
+    readonly suspension?: InteractionSuspension;
+}
+export interface PolicyEvaluationResult {
+    readonly decision: PolicyDecision;
+    readonly matchedRules: readonly PolicyRuleMatch[];
+    /** Optional policy ceiling. It may only narrow the request scope. */
+    readonly scope?: RequestedCapabilityScope;
+    readonly sandbox?: SandboxAttestation;
+}
+export interface AuditRedactionState {
+    readonly redacted: boolean;
+    readonly truncated: boolean;
+    readonly fields: readonly string[];
+}
+export interface AuditEventBase {
+    readonly version: "1";
+    readonly eventType: "policy.pre" | "policy.post";
+    readonly eventId: string;
+    readonly timestamp: string;
+    readonly correlationId: string;
+    readonly decisionId: string;
+    readonly principalId?: string;
+    readonly sessionId?: string;
+    readonly turnId?: string;
+    readonly workflow: WorkflowIdentity;
+    readonly step: StepIdentity;
+    readonly attempt: number;
+    readonly runtime?: string;
+    readonly transport?: string;
+    readonly manifest: CapabilityManifestV1 | null;
+    readonly scope: RequestedCapabilityScope;
+    readonly layers: readonly PolicyLayer[];
+    readonly matchedRules: readonly PolicyRuleMatch[];
+    readonly decision: PolicyDecision;
+    readonly attribution?: InteractionAttribution;
+    readonly sandbox: {
+        required: boolean;
+        verified: boolean;
+    };
+    readonly cached: boolean;
+    readonly redaction: AuditRedactionState;
+}
+export interface PreExecutionAuditEvent extends AuditEventBase {
+    readonly eventType: "policy.pre";
+}
+export interface PostExecutionAuditEvent extends AuditEventBase {
+    readonly eventType: "policy.post";
+    readonly durationMs: number;
+    readonly outcome: "success" | "failure" | "cancelled";
+    readonly errorCode?: string;
+}
+export interface PolicyProvider {
+    evaluate(request: PolicyRequest): Promise<PolicyEvaluationResult>;
+}
+export interface AuditSink {
+    append(event: PreExecutionAuditEvent | PostExecutionAuditEvent | import("./SecretContracts.js").SecretResolutionAuditEvent): Promise<void>;
+}
+export interface InteractionRequest {
+    readonly id: string;
+    readonly decision: PolicyDecision;
+    readonly request: PolicyRequest;
+    /**
+     * Durable run identity used by the control plane to resume the existing
+     * execution. This is a reference to persisted trace state, not a copy of
+     * workflow data or secrets.
+     */
+    readonly suspension?: InteractionSuspension;
+}
+export interface InteractionSuspension {
+    readonly runId: string;
+    readonly status: "suspended";
+    readonly step: StepIdentity;
+    readonly cursor: {
+        readonly stepIndex: number;
+        readonly deep: boolean;
+        readonly nodeRunId?: string;
+        readonly lastCompletedStepIndex?: number;
+    };
+    readonly trace: {
+        readonly workflow: WorkflowIdentity;
+        readonly parentRunId?: string;
+        readonly parentNodeRunId?: string;
+    };
+}
+export interface InteractionSuspensionPort {
+    suspend(request: InteractionRequest): Promise<void>;
+}

package/dist/PolicyContracts.js

@@ -0,0 +1 @@
+export {};

package/dist/ProcessCapabilityContracts.d.ts

@@ -0,0 +1,146 @@
+import { capabilityScope } from "./CapabilityContracts.js";
+import type { CapabilityOwner, CapabilityRequestContext, WorkspacePathRef } from "./CapabilityContracts.js";
+import type { PolicyEvaluationResult, PolicyRequest } from "./PolicyContracts.js";
+export declare const PROCESS_CAPABILITY_CONTRACT_VERSION: "1";
+export declare const PROCESS_DEFAULT_LIMITS: {
+    readonly maxWallTimeMs: 120000;
+    readonly maxCpuTimeMs: 60000;
+    readonly maxMemoryBytes: number;
+    readonly maxOutputBytes: number;
+    readonly maxInputBytes: number;
+    readonly maxProcesses: 1;
+};
+export declare const PROCESS_CAPABILITY_IDS: readonly ["process.exec", "process.pty", "shell.exec"];
+export type ProcessCapabilityId = (typeof PROCESS_CAPABILITY_IDS)[number];
+export type ProcessLifecycleStatus = "starting" | "running" | "exited" | "failed" | "cancelled" | "orphaned" | "cleaned";
+export interface ProcessEnvironmentBinding {
+    readonly name: string;
+    readonly source: "host" | "secret";
+    /** Host environment variable name or opaque SecretRef name; never a value. */
+    readonly reference: string;
+}
+export interface NetworkDestination {
+    readonly protocol: "tcp" | "udp";
+    readonly host: string;
+    readonly port: number;
+}
+export type ProcessNetworkPolicy = {
+    readonly mode: "none";
+} | {
+    readonly mode: "allowlist";
+    readonly destinations: readonly NetworkDestination[];
+};
+export interface ProcessResourceLimits {
+    readonly maxWallTimeMs: number;
+    readonly maxCpuTimeMs: number;
+    readonly maxMemoryBytes: number;
+    readonly maxOutputBytes: number;
+    readonly maxInputBytes: number;
+    readonly maxProcesses: number;
+}
+export interface ProcessSpecBase {
+    readonly version: typeof PROCESS_CAPABILITY_CONTRACT_VERSION;
+    readonly cwd: WorkspacePathRef;
+    readonly env: readonly ProcessEnvironmentBinding[];
+    readonly stdin: "closed" | "provided";
+    readonly terminal: "pipe" | "pty";
+    readonly limits: ProcessResourceLimits;
+    readonly network: ProcessNetworkPolicy;
+    readonly background: "foreground" | "durable";
+}
+/** Structured execution. Providers must pass executable/args to spawn with shell disabled. */
+export interface ExecutableProcessSpec extends ProcessSpecBase {
+    readonly mode: "executable";
+    readonly executable: string;
+    readonly args: readonly string[];
+}
+/** Shell parsing is an explicit, separately policy-classified capability. */
+export interface ShellStringProcessSpec extends ProcessSpecBase {
+    readonly mode: "shell-string";
+    readonly shell: string;
+    readonly command: string;
+}
+export type ProcessSpec = ExecutableProcessSpec | ShellStringProcessSpec;
+export interface ProcessStartRequest extends CapabilityRequestContext {
+    readonly policy: PolicyRequest;
+    readonly spec: ProcessSpec;
+    readonly owner: CapabilityOwner;
+}
+export type ProcessStartResult = {
+    readonly kind: "started";
+    readonly handle: ProcessHandle;
+} | {
+    readonly kind: "completed";
+    readonly result: ProcessResult;
+};
+export interface ProcessHandle {
+    readonly version: typeof PROCESS_CAPABILITY_CONTRACT_VERSION;
+    readonly id: string;
+    readonly owner: CapabilityOwner;
+    readonly specDigest: string;
+    readonly status: ProcessLifecycleStatus;
+    readonly startedAt: string;
+    readonly updatedAt: string;
+    readonly pid?: number;
+    readonly terminal: "pipe" | "pty";
+    readonly background: "foreground" | "durable";
+    readonly outputBytes: number;
+    readonly outputTruncated: boolean;
+}
+export interface ProcessOutputChunk {
+    readonly stream: "stdout" | "stderr";
+    readonly sequence: number;
+    readonly data: string;
+    readonly byteLength: number;
+}
+export interface ProcessOutputSnapshot {
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly capturedBytes: number;
+    readonly totalBytes: number;
+    readonly truncated: boolean;
+}
+export interface ProcessResult {
+    readonly handle: ProcessHandle;
+    readonly status: "exited" | "failed" | "cancelled";
+    readonly exitCode?: number;
+    readonly signal?: string;
+    readonly output: ProcessOutputSnapshot;
+    readonly durationMs: number;
+}
+export interface ProcessHandleRequest extends CapabilityRequestContext {
+    readonly policy: PolicyRequest;
+    readonly handle: ProcessHandle;
+}
+export interface ProcessCancellationRequest extends ProcessHandleRequest {
+    readonly reason: "user" | "timeout" | "policy" | "session-closed" | "orphan-cleanup";
+    readonly gracePeriodMs: number;
+}
+export interface ProcessOrphanCleanupRequest extends CapabilityRequestContext {
+    readonly policy: PolicyRequest;
+    readonly owner: CapabilityOwner;
+    readonly olderThan: string;
+}
+export interface ProcessCapability {
+    /** Durable/background starts return a handle; foreground starts may complete inline. */
+    start(request: ProcessStartRequest): Promise<ProcessStartResult>;
+    inspect(request: ProcessHandleRequest): Promise<ProcessHandle>;
+    readOutput(request: ProcessHandleRequest): AsyncIterable<ProcessOutputChunk>;
+    cancel(request: ProcessCancellationRequest): Promise<ProcessHandle>;
+    cleanupOrphans(request: ProcessOrphanCleanupRequest): Promise<readonly ProcessHandle[]>;
+}
+export declare function parseProcessSpec(value: unknown): ProcessSpec;
+export declare function parseProcessHandle(value: unknown): ProcessHandle;
+export declare function parseProcessOutput(value: unknown): ProcessOutputSnapshot;
+export declare function parseProcessResult(value: unknown): ProcessResult;
+export declare function parseProcessOutputChunk(value: unknown): ProcessOutputChunk;
+export declare function parseProcessCancellationRequest(value: unknown): ProcessCancellationRequest;
+export declare function parseProcessOrphanCleanupRequest(value: unknown): ProcessOrphanCleanupRequest;
+export declare function processCapabilityId(spec: ProcessSpec): ProcessCapabilityId;
+export declare function processCapabilityScope(spec: ProcessSpec): ReturnType<typeof capabilityScope>;
+export declare function assertProcessPolicyAllowed(spec: ProcessSpec, result: PolicyEvaluationResult): void;
+export declare function assertProcessOwner(handle: ProcessHandle, owner: CapabilityOwner): void;
+export declare function assertBoundedOutputChunk(value: ProcessOutputChunk): void;
+export declare function processWorkspaceCwd(spec: ProcessSpec): WorkspacePathRef;
+/** A durable run must remain addressable; a foreground run must be complete. */
+export declare function assertProcessStartResult(spec: ProcessSpec, result: ProcessStartResult): void;

package/dist/ProcessCapabilityContracts.js

@@ -0,0 +1,263 @@
+import { z } from "zod";
+import { AGENT_CAPABILITY_CONTRACT_VERSION, CAPABILITY_MAX_ID_LENGTH, CAPABILITY_MAX_LIST_ITEMS, CAPABILITY_MAX_OUTPUT_CHUNK_BYTES, CapabilityContractError, CapabilityOwnerSchema, WorkspacePathRefSchema, assertAuthorized, assertOwned, capabilityScope, identifier, parseCapabilityOwner, timestamp, } from "./CapabilityContracts.js";
+export const PROCESS_CAPABILITY_CONTRACT_VERSION = AGENT_CAPABILITY_CONTRACT_VERSION;
+export const PROCESS_DEFAULT_LIMITS = {
+    maxWallTimeMs: 120_000,
+    maxCpuTimeMs: 60_000,
+    maxMemoryBytes: 512 * 1024 * 1024,
+    maxOutputBytes: 4 * 1024 * 1024,
+    maxInputBytes: 1 * 1024 * 1024,
+    maxProcesses: 1,
+};
+export const PROCESS_CAPABILITY_IDS = ["process.exec", "process.pty", "shell.exec"];
+const envName = z
+    .string()
+    .min(1)
+    .max(256)
+    .regex(/^[A-Za-z_][A-Za-z0-9_]*$/);
+const envBindingSchema = z.object({ name: envName, source: z.enum(["host", "secret"]), reference: identifier });
+const networkSchema = z.discriminatedUnion("mode", [
+    z.object({ mode: z.literal("none") }),
+    z.object({
+        mode: z.literal("allowlist"),
+        destinations: z
+            .array(z.object({
+            protocol: z.enum(["tcp", "udp"]),
+            host: z
+                .string()
+                .min(1)
+                .max(253)
+                .regex(/^[A-Za-z0-9.-]+$/),
+            port: z.number().int().min(1).max(65_535),
+        }))
+            .min(1)
+            .max(128),
+    }),
+]);
+const limitsSchema = z.object({
+    maxWallTimeMs: z.number().int().positive().max(86_400_000).default(PROCESS_DEFAULT_LIMITS.maxWallTimeMs),
+    maxCpuTimeMs: z.number().int().positive().max(86_400_000).default(PROCESS_DEFAULT_LIMITS.maxCpuTimeMs),
+    maxMemoryBytes: z
+        .number()
+        .int()
+        .positive()
+        .max(8 * 1024 * 1024 * 1024)
+        .default(PROCESS_DEFAULT_LIMITS.maxMemoryBytes),
+    maxOutputBytes: z
+        .number()
+        .int()
+        .positive()
+        .max(256 * 1024 * 1024)
+        .default(PROCESS_DEFAULT_LIMITS.maxOutputBytes),
+    maxInputBytes: z
+        .number()
+        .int()
+        .positive()
+        .max(256 * 1024 * 1024)
+        .default(PROCESS_DEFAULT_LIMITS.maxInputBytes),
+    maxProcesses: z.number().int().positive().max(256).default(PROCESS_DEFAULT_LIMITS.maxProcesses),
+});
+const baseSchema = z.object({
+    version: z.literal(PROCESS_CAPABILITY_CONTRACT_VERSION),
+    cwd: WorkspacePathRefSchema,
+    env: z.array(envBindingSchema).max(CAPABILITY_MAX_LIST_ITEMS).default([]),
+    stdin: z.enum(["closed", "provided"]).default("closed"),
+    terminal: z.enum(["pipe", "pty"]).default("pipe"),
+    limits: limitsSchema.default(PROCESS_DEFAULT_LIMITS),
+    network: networkSchema.default({ mode: "none" }),
+    background: z.enum(["foreground", "durable"]).default("foreground"),
+});
+const executableSchema = baseSchema.extend({
+    mode: z.literal("executable"),
+    executable: z
+        .string()
+        .min(1)
+        .max(CAPABILITY_MAX_ID_LENGTH)
+        .regex(/^[^\s\0;&|<>`$]+$/),
+    args: z
+        .array(z
+        .string()
+        .max(16_384)
+        .refine((value) => !value.includes("\0"), "must not contain NUL"))
+        .max(CAPABILITY_MAX_LIST_ITEMS),
+});
+const shellSchema = baseSchema.extend({
+    mode: z.literal("shell-string"),
+    shell: z
+        .string()
+        .min(1)
+        .max(CAPABILITY_MAX_ID_LENGTH)
+        .regex(/^[^\s\0;&|<>`$]+$/),
+    command: z
+        .string()
+        .min(1)
+        .max(256 * 1024)
+        .refine((value) => !value.includes("\0"), "must not contain NUL"),
+});
+const processSchema = z.discriminatedUnion("mode", [executableSchema, shellSchema]);
+const digestSchema = z
+    .string()
+    .regex(/^(?:sha256):[0-9a-f]{64}$|^(?:sha512):[0-9a-f]{128}$/i)
+    .transform((value) => value.toLowerCase());
+const handleSchema = z.object({
+    version: z.literal(PROCESS_CAPABILITY_CONTRACT_VERSION),
+    id: identifier,
+    owner: CapabilityOwnerSchema,
+    specDigest: digestSchema,
+    status: z.enum(["starting", "running", "exited", "failed", "cancelled", "orphaned", "cleaned"]),
+    startedAt: timestamp,
+    updatedAt: timestamp,
+    pid: z.number().int().positive().max(4_194_304).optional(),
+    terminal: z.enum(["pipe", "pty"]),
+    background: z.enum(["foreground", "durable"]),
+    outputBytes: z
+        .number()
+        .int()
+        .nonnegative()
+        .max(256 * 1024 * 1024),
+    outputTruncated: z.boolean(),
+});
+const outputSchema = z.object({
+    stdout: z.string(),
+    stderr: z.string(),
+    capturedBytes: z
+        .number()
+        .int()
+        .nonnegative()
+        .max(256 * 1024 * 1024),
+    totalBytes: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
+    truncated: z.boolean(),
+});
+const resultSchema = z
+    .object({
+    handle: handleSchema,
+    status: z.enum(["exited", "failed", "cancelled"]),
+    exitCode: z.number().int().min(-255).max(255).optional(),
+    signal: identifier.optional(),
+    output: outputSchema,
+    durationMs: z.number().int().nonnegative().max(86_400_000),
+})
+    .superRefine((value, context) => {
+    if (value.handle.status !== value.status)
+        context.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["handle", "status"],
+            message: "must match result status",
+        });
+});
+const chunkSchema = z.object({
+    stream: z.enum(["stdout", "stderr"]),
+    sequence: z.number().int().nonnegative(),
+    data: z.string(),
+    byteLength: z.number().int().nonnegative().max(CAPABILITY_MAX_OUTPUT_CHUNK_BYTES),
+});
+function parse(schema, value, label) {
+    const result = schema.safeParse(value);
+    if (!result.success)
+        throw new CapabilityContractError(`${label}: ${result.error.issues.map((issue) => issue.message).join("; ")}`);
+    return result.data;
+}
+function immutable(value) {
+    const snapshot = structuredClone(value);
+    const freeze = (item) => {
+        if (item === null || typeof item !== "object" || Object.isFrozen(item))
+            return;
+        for (const child of Object.values(item))
+            freeze(child);
+        Object.freeze(item);
+    };
+    freeze(snapshot);
+    return snapshot;
+}
+export function parseProcessSpec(value) {
+    const spec = parse(processSchema, value, "process spec");
+    const names = new Set();
+    for (const binding of spec.env) {
+        if (names.has(binding.name))
+            throw new CapabilityContractError(`process spec: duplicate environment name ${binding.name}`);
+        names.add(binding.name);
+        if (binding.source === "host" && !/^[A-Za-z_][A-Za-z0-9_]*$/.test(binding.reference))
+            throw new CapabilityContractError(`process spec: host environment reference ${binding.reference} is invalid`);
+    }
+    return immutable(spec);
+}
+export function parseProcessHandle(value) {
+    return immutable(parse(handleSchema, value, "process handle"));
+}
+export function parseProcessOutput(value) {
+    const output = parse(outputSchema, value, "process output");
+    const capturedBytes = new TextEncoder().encode(`${output.stdout}${output.stderr}`).byteLength;
+    if (capturedBytes !== output.capturedBytes)
+        throw new CapabilityContractError("process output capturedBytes is incorrect");
+    if (output.capturedBytes > output.totalBytes)
+        throw new CapabilityContractError("process output capturedBytes exceeds totalBytes");
+    return immutable(output);
+}
+export function parseProcessResult(value) {
+    const result = parse(resultSchema, value, "process result");
+    const output = parseProcessOutput(result.output);
+    return immutable({ ...result, output });
+}
+export function parseProcessOutputChunk(value) {
+    const chunk = parse(chunkSchema, value, "process output chunk");
+    const byteLength = new TextEncoder().encode(chunk.data).byteLength;
+    if (byteLength !== chunk.byteLength)
+        throw new CapabilityContractError("process output chunk byteLength is incorrect");
+    return immutable(chunk);
+}
+export function parseProcessCancellationRequest(value) {
+    const schema = z.object({
+        policy: z.custom(),
+        owner: CapabilityOwnerSchema,
+        handle: handleSchema,
+        reason: z.enum(["user", "timeout", "policy", "session-closed", "orphan-cleanup"]),
+        gracePeriodMs: z.number().int().nonnegative().max(60_000),
+    });
+    return immutable(parse(schema, value, "process cancellation request"));
+}
+export function parseProcessOrphanCleanupRequest(value) {
+    const schema = z.object({
+        policy: z.custom(),
+        owner: CapabilityOwnerSchema,
+        olderThan: timestamp,
+    });
+    return immutable(parse(schema, value, "process orphan cleanup request"));
+}
+export function processCapabilityId(spec) {
+    if (spec.mode === "shell-string")
+        return "shell.exec";
+    return spec.terminal === "pty" ? "process.pty" : "process.exec";
+}
+export function processCapabilityScope(spec) {
+    const effects = ["process"];
+    const capabilities = [processCapabilityId(spec)];
+    const secrets = spec.env.filter((binding) => binding.source === "secret").map((binding) => binding.reference);
+    const withTerminal = spec.terminal === "pty" ? [...effects, "streaming"] : [...effects];
+    if (spec.network.mode === "allowlist")
+        return capabilityScope([...withTerminal, "network"], capabilities, secrets);
+    return capabilityScope(withTerminal, capabilities, secrets);
+}
+export function assertProcessPolicyAllowed(spec, result) {
+    if (spec.mode === "shell-string" && result.decision.kind !== "allow")
+        throw new CapabilityContractError(`shell-string execution requires explicit allow policy: ${result.decision.kind}`);
+    if (spec.mode === "shell-string" && result.decision.kind === "require-sandbox")
+        throw new CapabilityContractError("shell-string execution requires an explicit allow decision");
+    assertAuthorized(result, { allowSandbox: true });
+}
+export function assertProcessOwner(handle, owner) {
+    assertOwned(handle.owner, parseCapabilityOwner(owner));
+}
+export function assertBoundedOutputChunk(value) {
+    if (new TextEncoder().encode(value.data).byteLength > CAPABILITY_MAX_OUTPUT_CHUNK_BYTES)
+        throw new CapabilityContractError("process output chunk exceeds the hard byte bound");
+}
+export function processWorkspaceCwd(spec) {
+    return spec.cwd;
+}
+/** A durable run must remain addressable; a foreground run must be complete. */
+export function assertProcessStartResult(spec, result) {
+    if (spec.background === "durable" && result.kind !== "started")
+        throw new CapabilityContractError("durable process execution must return a background handle");
+    if (spec.background === "foreground" && result.kind !== "completed")
+        throw new CapabilityContractError("foreground process execution must complete inline");
+}