Interface: SandboxPolicyEnforcer
Defined in: src/batteries/sandbox/contracts/policy_enforcer.ts:6
Policy boundary. run resolves on spawn and exposes live streams plus a later completion promise.
Properties
| Property | Modifier | Type | Description | Defined in |
|---|---|---|---|---|
adopted? | readonly | boolean | Whether this adapter adopted an already-enabled process-global sandbox rather than initializing it. | src/batteries/sandbox/contracts/policy_enforcer.ts:10 |
Methods
checkDependencies()
checkDependencies(): Promise<{
errors: string[];
warnings: string[];
}>;Defined in: src/batteries/sandbox/contracts/policy_enforcer.ts:12
Probe external prerequisites. A non-empty errors throws E_SANDBOX_DEPENDENCY_MISSING; warnings are surfaced through observability and are NOT fatal.
Returns
Promise<{ errors: string[]; warnings: string[]; }>
diagnosticsFor()
diagnosticsFor(correlationId: string): string[];Defined in: src/batteries/sandbox/contracts/policy_enforcer.ts:64
Retrieve diagnostics by correlation id, never by command text.
Parameters
| Parameter | Type |
|---|---|
correlationId | string |
Returns
string[]
dispose()
dispose(): Promise<void>;Defined in: src/batteries/sandbox/contracts/policy_enforcer.ts:66
Release what this enforcer OWNS. A no-op when it adopted a foreign sandbox — tearing down a manager we did not initialize would strip ACEs a host app depends on.
Returns
Promise<void>
effectivePolicy()
effectivePolicy(): DerivedRules | undefined;Defined in: src/batteries/sandbox/contracts/policy_enforcer.ts:62
Return the opaque derived snapshot used for drift validation.
Returns
DerivedRules | undefined
isSupported()
isSupported(): boolean;Defined in: src/batteries/sandbox/contracts/policy_enforcer.ts:8
Whether this enforcer can enforce on the current platform. false (a browser tab, where SRT does not exist) raises E_SANDBOX_UNSUPPORTED_ENV at construction rather than degrading — a shim that enforces nothing reads as sandboxed.
Returns
boolean
run()
run(op: {
argv: string[];
correlationId: string;
cwd: string;
env?: Record<string, string>;
policy: SandboxPolicy;
signal?: AbortSignal;
}): Promise<{
completed: Promise<{
exitCode: number;
failed: boolean;
signalCode?: string;
}>;
stderr: ReadableStream<Uint8Array<ArrayBufferLike>>;
stdout: ReadableStream<Uint8Array<ArrayBufferLike>>;
}>;Defined in: src/batteries/sandbox/contracts/policy_enforcer.ts:22
Spawn under a narrowing policy; a non-zero exit is data, not a rejected promise.
Parameters
| Parameter | Type | Description |
|---|---|---|
op | { argv: string[]; correlationId: string; cwd: string; env?: Record<string, string>; policy: SandboxPolicy; signal?: AbortSignal; } | - |
op.argv | string[] | - |
op.correlationId | string | - |
op.cwd | string | - |
op.env? | Record<string, string> | The caller's own EXPLICIT environment values, applied LAST. Remarks NOT the host-inheritance control. What a child inherits from the host is the ADAPTER's decision, expressed as an allow-list the adapter owns (the Node/SRT one denies by default and takes that allow-list at construction). This field is the other half of the picture: the values the caller names itself. They may add names, or override inherited ones, and because they are applied last they also win a collision with an allow-listed name. An adapter MUST NOT let env — or anything else — cause host variables BEYOND its allow-list to reach the child. Concretely, it must not merge the rest of process.env back in on top, and it must not treat the presence of env as a trigger to inherit more widely. Leaving these semantics unstated is how the Node adapter came to spread the entire process.env into every child while this field sat unused. |
op.policy | SandboxPolicy | - |
op.signal? | AbortSignal | Lifecycle cancellation for this child. Implementations must kill the spawned child and settle completed when this signal aborts. |
Returns
Promise<{ completed: Promise<{ exitCode: number; failed: boolean; signalCode?: string; }>; stderr: ReadableStream<Uint8Array<ArrayBufferLike>>; stdout: ReadableStream<Uint8Array<ArrayBufferLike>>; }>
Remarks
When op.signal aborts, an implementation MUST terminate the spawned child (including a child hidden behind a sandbox wrapper) and settle completed; it MUST NOT leave the child running after the lifecycle owner has cancelled the invocation. The returned streams may end as a consequence of termination, but completed remains the authoritative settlement signal.