@clementine-solutions/jane-io 1.0.0 → 1.0.2

package/dist/core/parsers/parse-numeric-string.js

@@ -0,0 +1,29 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Parsers | Parse Numeric String
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Parses strict numeric strings into numbers, supporting
+ *                  optional decimals while rejecting ambiguous formats.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { parseEvent } from '../pipeline';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Implementation                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Parses strict numeric strings into JavaScript numbers, supporting optional
+ * decimals while rejecting scientific notation and non‑numeric characters.
+ */
+export const parseNumericString = (value, path) => {
+    if (typeof value !== 'string')
+        return [];
+    if (!/^-?\d+(\.\d+)?$/.test(value))
+        return [];
+    const parsed = Number(value);
+    if (Number.isNaN(parsed))
+        return [];
+    const event = parseEvent('info', 'string.now.number', `String parsed into number ${parsed}.`, path, 'Converted text into a number.', { before: value, after: parsed });
+    return [{ path, nextValue: parsed, events: [event] }];
+};

package/dist/core/parsers/parse-object-string.d.ts

@@ -0,0 +1,16 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Parsers | Parse Object String
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Parses JSON object strings into plain objects, rejecting
+ *                  arrays, null, and non‑object structures.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import type { ParseRule } from '../shapes';
+/**
+ * Parses JSON object strings into plain objects, rejecting arrays, null, and
+ * any non‑object structures.
+ */
+export declare const parseObjectString: ParseRule<unknown>;

package/dist/core/parsers/parse-object-string.js

@@ -0,0 +1,36 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Parsers | Parse Object String
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Parses JSON object strings into plain objects, rejecting
+ *                  arrays, null, and non‑object structures.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { parseEvent } from '../pipeline';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Implementation                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Parses JSON object strings into plain objects, rejecting arrays, null, and
+ * any non‑object structures.
+ */
+export const parseObjectString = (value, path) => {
+    if (typeof value !== 'string')
+        return [];
+    const trimmed = value.trim();
+    if (!trimmed.startsWith('{') || !trimmed.endsWith('}'))
+        return [];
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
+    }
+    catch {
+        return [];
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+        return [];
+    const event = parseEvent('info', 'string.now.object', 'String parsed into JSON object.', path, 'Converted text into an object.', { before: value, after: parsed });
+    return [{ path, nextValue: parsed, events: [event] }];
+};

package/dist/core/parsers/parse-octal-string.d.ts

@@ -0,0 +1,16 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Parsers | Parse Octal String
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Parses octal string literals (`0o…`) into `bigint` values,
+ *                  enforcing strict base‑8 formatting.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import type { ParseRule } from '../shapes';
+/**
+ * Parses octal string literals (`0o…`) into `bigint` values, validating format
+ * and rejecting malformed or non‑octal input.
+ */
+export declare const parseOctalString: ParseRule<unknown>;

package/dist/core/parsers/parse-octal-string.js

@@ -0,0 +1,33 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Parsers | Parse Octal String
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Parses octal string literals (`0o…`) into `bigint` values,
+ *                  enforcing strict base‑8 formatting.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { parseEvent } from '../pipeline';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Implementation                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Parses octal string literals (`0o…`) into `bigint` values, validating format
+ * and rejecting malformed or non‑octal input.
+ */
+export const parseOctalString = (value, path) => {
+    if (typeof value !== 'string')
+        return [];
+    if (!/^0o[0-7]+$/.test(value))
+        return [];
+    let parsed;
+    try {
+        parsed = BigInt(value);
+    }
+    catch {
+        return [];
+    }
+    const event = parseEvent('info', 'string.now.octal', `Octal string parsed into bigint ${parsed}.`, path, 'Converted octal text into a number.', { before: value, after: parsed });
+    return [{ path, nextValue: parsed, events: [event] }];
+};

package/dist/core/parsers/parse-scientific-notation-string.d.ts

@@ -0,0 +1,16 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Parsers | Parse Scientific Notation String
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Parses strict scientific‑notation strings into numbers,
+ *                  validating both mantissa and exponent format.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import type { ParseRule } from '../shapes';
+/**
+ * Parses strict scientific‑notation strings into numbers, enforcing canonical
+ * formatting for both mantissa and exponent.
+ */
+export declare const parseScientificNotationString: ParseRule<unknown>;

package/dist/core/parsers/parse-scientific-notation-string.js

@@ -0,0 +1,30 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Parsers | Parse Scientific Notation String
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Parses strict scientific‑notation strings into numbers,
+ *                  validating both mantissa and exponent format.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { parseEvent } from '../pipeline';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Implementation                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Parses strict scientific‑notation strings into numbers, enforcing canonical
+ * formatting for both mantissa and exponent.
+ */
+export const parseScientificNotationString = (value, path) => {
+    if (typeof value !== 'string')
+        return [];
+    // Strict scientific notation: digits, optional decimal, 'e' or 'E', signed exponent
+    if (!/^-?\d+(\.\d+)?[eE][+-]?\d+$/.test(value))
+        return [];
+    const parsed = Number(value);
+    if (Number.isNaN(parsed))
+        return [];
+    const event = parseEvent('info', 'string.now.scientific', `String parsed into number ${parsed} using scientific notation.`, path, 'Converted scientific notation into a number.', { before: value, after: parsed });
+    return [{ path, nextValue: parsed, events: [event] }];
+};

package/dist/core/parsers/parse-url-string.d.ts

@@ -0,0 +1,16 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Parsers | Parse URL String
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Parses URL strings into normalized URL values, ensuring the
+ *                  text represents a valid, fully qualified URL.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import type { ParseRule } from '../shapes';
+/**
+ * Parses URL strings into normalized URL values, ensuring the text represents
+ * a syntactically valid and fully qualified URL.
+ */
+export declare const parseUrlString: ParseRule<string>;

package/dist/core/parsers/parse-url-string.js

@@ -0,0 +1,36 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Parsers | Parse URL String
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Parses URL strings into normalized URL values, ensuring the
+ *                  text represents a valid, fully qualified URL.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { parseEvent } from '../pipeline';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Implementation                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Parses URL strings into normalized URL values, ensuring the text represents
+ * a syntactically valid and fully qualified URL.
+ */
+export const parseUrlString = (value, path) => {
+    if (typeof value !== 'string')
+        return [];
+    try {
+        const normalized = new URL(value).toString();
+        const event = parseEvent('info', 'string.now.url', `String parsed into URL (${normalized}).`, path, 'Converted text into a URL.', { before: value, after: normalized });
+        return [
+            {
+                path,
+                nextValue: normalized,
+                events: [event],
+            },
+        ];
+    }
+    catch {
+        return [];
+    }
+};

package/dist/core/pipeline/boundary.d.ts

@@ -0,0 +1,36 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Pipeline | Boundary
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Aggregates field results and applies boundary‑level policy
+ *                  to produce a final decision.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import type { BoundaryContext, BoundaryDecision, BoundaryInput, BoundaryResult } from '../shapes';
+import type { BoundaryRule } from '../shapes/boundary';
+/**
+ * Holds all registered boundary‑level rules.
+ *
+ * Provides a central lookup for rule names used in boundary policies,
+ * allowing contributors to extend or customize boundary evaluation
+ * without modifying the core engine.
+ */
+export declare const boundaryRuleRegistry: Record<string, BoundaryRule>;
+/**
+ * Executes boundary evaluation across all field results.
+ *
+ * Aggregates issues and events from each pipeline result, applies
+ * boundary‑level rules, shapes values and metadata according to policy,
+ * and produces the final boundary result used for acceptance decisions.
+ */
+export declare function boundaryRunner(input: BoundaryInput): Promise<BoundaryResult>;
+/**
+ * Applies boundary decision logic to the aggregated context.
+ *
+ * Shapes events and issues through ignore, override, escalate, and
+ * visibility rules, evaluates acceptance modes, and optionally invokes
+ * a reducer to refine or override the final decision.
+ */
+export declare function decideBoundary(context: BoundaryContext): Promise<BoundaryDecision>;

package/dist/core/pipeline/boundary.js

@@ -0,0 +1,256 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Pipeline | Boundary
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Aggregates field results and applies boundary‑level policy
+ *                  to produce a final decision.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { applyEscalate, applyOverride, defaultPolicy, generateRunId, matchesWildcard, resolveLevel, } from '../common';
+import { boundaryPolicyDefault } from '../common/policy';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Boundary Rule Registry                                                    *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Holds all registered boundary‑level rules.
+ *
+ * Provides a central lookup for rule names used in boundary policies,
+ * allowing contributors to extend or customize boundary evaluation
+ * without modifying the core engine.
+ */
+export const boundaryRuleRegistry = {};
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Boundary Runner                                                           *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Executes boundary evaluation across all field results.
+ *
+ * Aggregates issues and events from each pipeline result, applies
+ * boundary‑level rules, shapes values and metadata according to policy,
+ * and produces the final boundary result used for acceptance decisions.
+ */
+export async function boundaryRunner(input) {
+    const startedAt = new Date();
+    const runId = generateRunId();
+    const { policy = defaultPolicy, fields } = input;
+    const boundary = policy.boundary ?? boundaryPolicyDefault;
+    const allIssues = [];
+    const allEvents = [];
+    const metadata = {};
+    const value = {};
+    for (const key of Object.keys(fields)) {
+        const result = fields[key];
+        metadata[key] = {
+            raw: result.raw,
+            safe: result.safe,
+            final: result.final,
+            path: result.path,
+            rawType: result.rawType,
+            finalType: result.finalType,
+            startedAt: result.metadata.startedAt,
+            finishedAt: result.metadata.finishedAt,
+            durationMs: result.metadata.durationMs,
+            inputName: result.metadata.inputName,
+        };
+        if (result.decision?.code === 'accept') {
+            value[key] = result.final;
+        }
+        const events = result.events ?? [];
+        const issues = events.filter((e) => (e.kind === 'error' || e.kind === 'fatal') &&
+            typeof e.code === 'string' &&
+            e.code.trim().length > 0);
+        allIssues.push(...issues);
+        allEvents.push(...events);
+    }
+    if (boundary?.rules && boundary.rules.length > 0) {
+        for (const rule of boundary.rules) {
+            const ctx = {
+                policy,
+                fields,
+                events: allEvents,
+                issues: allIssues,
+                values: value,
+            };
+            try {
+                const result = await rule(ctx);
+                if (!result)
+                    continue;
+                if (result.events)
+                    allEvents.push(...result.events);
+                if (result.issues)
+                    allIssues.push(...result.issues);
+            }
+            catch (error) {
+                allEvents.push({
+                    phase: 'decide',
+                    kind: 'fatal',
+                    code: 'boundary.fatal.error',
+                    message: error?.message ?? 'Unknown error',
+                });
+            }
+        }
+    }
+    const finishedAt = new Date();
+    const decision = await decideBoundary({
+        policy,
+        fields,
+        issues: allIssues,
+        events: allEvents,
+        values: value,
+    });
+    let shapedValues = { ...value };
+    if (boundary?.values?.includeRejected) {
+        for (const key of Object.keys(fields)) {
+            const r = fields[key];
+            if (r.decision?.code !== 'accept') {
+                shapedValues[key] = r.final;
+            }
+        }
+    }
+    if (boundary?.values?.includeUndefined) {
+        for (const key of Object.keys(fields)) {
+            if (!(key in shapedValues)) {
+                shapedValues[key] = undefined;
+            }
+        }
+    }
+    if (boundary?.values?.transform) {
+        shapedValues = boundary.values.transform(shapedValues);
+    }
+    let shapedMetadata = {
+        runId,
+        startedAt: startedAt.toISOString(),
+        finishedAt: finishedAt.toISOString(),
+        durationMs: finishedAt.getTime() - startedAt.getTime(),
+        fields: metadata,
+        boundaryName: policy.boundaryName,
+        pipelineName: policy.pipelineName,
+        analysis: {
+            diff: policy.analysis?.diff,
+            explain: policy.analysis?.explain,
+            replay: policy.analysis?.replay,
+            telemetry: policy.analysis?.telemetry,
+        },
+    };
+    if (boundary?.metadata) {
+        const m = boundary.metadata;
+        if (m.includeFields === false) {
+            shapedMetadata = { ...shapedMetadata, fields: {} };
+        }
+        if (m.includeTimestamps === false) {
+            shapedMetadata = {
+                ...shapedMetadata,
+                startedAt: undefined,
+                finishedAt: undefined,
+                durationMs: undefined,
+            };
+        }
+        if (m.includeRunId === false) {
+            shapedMetadata = { ...shapedMetadata, runId: undefined };
+        }
+    }
+    return {
+        ok: decision.ok,
+        issues: decision.issues ?? (allIssues.length > 0 ? allIssues : undefined),
+        events: decision.events ?? (allEvents.length > 0 ? allEvents : undefined),
+        values: decision.values ?? shapedValues,
+        fields,
+        metadata: decision.metadata ?? shapedMetadata,
+    };
+}
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Decide Boundary                                                           *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Applies boundary decision logic to the aggregated context.
+ *
+ * Shapes events and issues through ignore, override, escalate, and
+ * visibility rules, evaluates acceptance modes, and optionally invokes
+ * a reducer to refine or override the final decision.
+ */
+export async function decideBoundary(context) {
+    const { policy, fields } = context;
+    const boundary = policy.boundary;
+    let shapedEvents = [...context.events];
+    if (boundary?.ignore) {
+        shapedEvents = shapedEvents.filter((ev) => !matchesWildcard(ev.code, boundary.ignore));
+    }
+    if (boundary?.override) {
+        shapedEvents = shapedEvents.map((ev) => {
+            const level = resolveLevel(ev.code, boundary.override);
+            return level === undefined ? ev : { ...ev, kind: applyOverride(ev.kind, level) };
+        });
+    }
+    if (boundary?.escalate) {
+        shapedEvents = shapedEvents.map((ev) => {
+            const level = resolveLevel(ev.code, boundary.escalate);
+            return level === undefined ? ev : { ...ev, kind: applyEscalate(ev.kind, level) };
+        });
+    }
+    if (boundary?.hideEvents) {
+        shapedEvents = shapedEvents.filter((ev) => !matchesWildcard(ev.code, boundary.hideEvents));
+    }
+    let shapedIssues = shapedEvents.filter((ev) => (ev.kind === 'error' || ev.kind === 'fatal') &&
+        typeof ev.code === 'string' &&
+        ev.code.trim().length > 0);
+    if (boundary?.hideIssues) {
+        shapedIssues = shapedIssues.filter((ev) => !matchesWildcard(ev.code, boundary.hideIssues));
+    }
+    const rejectPatterns = boundary?.reject ?? policy.decide?.reject ?? [];
+    const reviewPatterns = boundary?.review ?? policy.decide?.review ?? [];
+    let hasReject = false;
+    let hasReview = false;
+    for (const ev of shapedEvents) {
+        if (ev.kind === 'fatal') {
+            hasReject = true;
+            continue;
+        }
+        if (matchesWildcard(ev.code, rejectPatterns)) {
+            hasReject = true;
+            continue;
+        }
+        if (matchesWildcard(ev.code, reviewPatterns)) {
+            hasReview = true;
+        }
+    }
+    const acceptMode = boundary?.accept ?? 'all';
+    let ok;
+    switch (acceptMode) {
+        case 'strict':
+            ok = !hasReject && !hasReview && shapedIssues.length === 0;
+            break;
+        case 'any':
+            ok = !hasReject && Object.values(fields).some((r) => r.decision?.code === 'accept');
+            break;
+        case 'partial':
+            ok = !hasReject;
+            break;
+        case 'all':
+        default:
+            ok =
+                !hasReject &&
+                    shapedIssues.length === 0 &&
+                    Object.values(fields).every((r) => r.decision?.code === 'accept');
+            break;
+    }
+    const shapedContext = {
+        ...context,
+        events: shapedEvents,
+        issues: shapedIssues,
+    };
+    if (boundary?.reducer) {
+        const result = await boundary.reducer(shapedContext);
+        if (result !== undefined) {
+            if ('ok' in result && typeof result.ok === 'boolean') {
+                return result;
+            }
+            return {
+                ok,
+                ...result,
+            };
+        }
+    }
+    return { ok };
+}

package/dist/core/pipeline/contain.d.ts

@@ -0,0 +1,122 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Pipeline | Contain
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Enforces structural limits and produces a safe, cycle‑free
+ *                  representation of input.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import type { ContainmentContext, ContainmentOptions, FieldPath, InternalJsonValue, Policy } from '../shapes';
+/**
+ * Sentinel markers used when a value cannot be safely contained.
+ *
+ * These appear when encountering cycles, excessive depth or size, unsafe
+ * structures, or disallowed types such as functions, symbols, and proxies.
+ */
+export declare const ContainmentSentinel: {
+    readonly Circular: "[Circular]";
+    readonly TooDeep: "[TooDeep]";
+    readonly TooLarge: "[TooLarge]";
+    readonly Proxy: "[Proxy]";
+    readonly Getter: "[Getter]";
+    readonly Function: "[Function]";
+    readonly Symbol: "[Symbol]";
+    readonly BigInt: "[BigInt]";
+};
+export type ContainmentSentinel = (typeof ContainmentSentinel)[keyof typeof ContainmentSentinel];
+/**
+ * Contains an array by applying depth and length limits.
+ *
+ * Recursively contains each element, records the container for cycle
+ * detection, and appends a TooLarge sentinel when the array exceeds
+ * the configured maximum length.
+ */
+export declare function containArray(value: readonly unknown[], path: FieldPath, context: ContainmentContext, depth: number): unknown;
+/**
+ * Represents a bigint value in a safe, JSON‑compatible form.
+ *
+ * Used only when bigint is explicitly allowed by policy; otherwise
+ * containment falls back to the BigInt sentinel.
+ */
+export declare function containBigInt(value: bigint): {
+    kind: "bigint";
+    asString: string;
+};
+/**
+ * Contains a plain object by enforcing key limits and safe property access.
+ *
+ * Skips prototype‑pollution vectors, replaces getters/setters with a
+ * Getter sentinel, and recursively contains each value. Adds a TooLarge
+ * sentinel entry when the object exceeds the configured key limit.
+ */
+export declare function containObject(value: Record<string, unknown>, path: FieldPath, ctx: ContainmentContext, depth: number): unknown;
+/**
+ * Recursively contains any value into a safe, JSON‑like structure.
+ *
+ * Enforces depth limits, detects cycles, handles primitives directly,
+ * applies policy‑controlled exceptions (e.g., bigint), and replaces
+ * unsafe or non‑plain objects with appropriate sentinels.
+ */
+export declare function containRecursive(value: unknown, path: FieldPath, context: ContainmentContext, depth: number): unknown;
+/**
+ * Entry point for containment.
+ *
+ * Creates a fresh containment context and produces a safe representation
+ * of the input value. Falls back to the Proxy sentinel if containment
+ * fails unexpectedly.
+ */
+export declare function containValue(value: unknown, path?: FieldPath, options?: ContainmentOptions, policy?: Policy): unknown;
+/**
+ * Constructs a containment context with structural limits, policy,
+ * and a fresh cycle‑detection map.
+ */
+export declare function createContainmentContext(options: ContainmentOptions, policy: Policy): ContainmentContext;
+/**
+ * Produces a deep, acyclic clone of an internal JSON value.
+ *
+ * Preserves primitives, arrays, plain objects, and Date instances while
+ * tracking references to avoid infinite recursion. Used to safely copy
+ * containment output without re‑running containment.
+ */
+export declare function deepClone(input: InternalJsonValue, seen?: WeakMap<object, InternalJsonValue>): InternalJsonValue | undefined;
+/**
+ * Default structural limits applied during containment.
+ *
+ * These bounds prevent excessive recursion and traversal by capping depth,
+ * array length, and object key count.
+ */
+export declare const defaultContainmentOptions: ContainmentOptions;
+/**
+ * Determines whether a value is a containment sentinel.
+ *
+ * Sentinels represent structural hazards or disallowed types encountered
+ * during containment and are encoded as well‑known string markers.
+ */
+export declare function isSentinel(value: unknown): value is ContainmentSentinel;
+/**
+ * Safely retrieves an object's own enumerable keys.
+ *
+ * Returns an empty array if key enumeration fails, protecting containment
+ * from objects with hostile or unusual prototypes.
+ */
+export declare function safeObjectKeys(value: Record<string, unknown>): string[];
+/**
+ * Safely retrieves a property descriptor.
+ *
+ * Returns undefined if descriptor access throws, allowing containment to
+ * gracefully handle objects with unsafe or non‑standard behavior.
+ */
+export declare function safePropertyDescriptor(value: Record<string, unknown>, key: string): PropertyDescriptor | undefined;
+/**
+ * Maps a containment sentinel to its corresponding event.
+ *
+ * Used to surface structural hazards—such as cycles, excessive depth,
+ * unsafe objects, or disallowed types—as typed events during scanning
+ * and policy evaluation.
+ */
+export declare function sentinelEvent(kind: ContainmentSentinel): {
+    code: string;
+    severity: string;
+};