@fractalcode/bridge 0.1.0

package/dist/src/compiler/index.js

@@ -0,0 +1,137 @@
+"use strict";
+/**
+ * fractal-openshell-bridge — the pure compiler function.
+ *
+ * `compileSidecars(channels, timestamp)` is a pure function:
+ *   - No filesystem, no network, no env, no clock reads (timestamp is a param).
+ *   - Input is deep-frozen on entry (downstream mappers cannot mutate it).
+ *   - Output is deterministic: identical channels → byte-identical policyYaml
+ *     → identical policyHash. The timestamp is NOT an input to the hash.
+ *   - Errors are returned as { success: false, code, error }, never thrown.
+ *
+ * Side effects (logging, persistence) are the caller's responsibility — the
+ * caller receives the auditLog in the result and persists it however it likes.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildFilesystem = exports.mapChannel = exports.serializePolicy = void 0;
+exports.compileSidecars = compileSidecars;
+const crypto_1 = require("crypto");
+const mappings_1 = require("./mappings");
+const serialize_1 = require("./serialize");
+/** Recursively freeze an object so downstream code cannot mutate the input. */
+function deepFreeze(value) {
+    if (value && typeof value === "object") {
+        Object.freeze(value);
+        for (const v of Object.values(value)) {
+            deepFreeze(v);
+        }
+    }
+    return value;
+}
+/** Validate that input is an array of TypedChannelConfig-shaped objects. */
+function validateInput(channels) {
+    if (!Array.isArray(channels)) {
+        return "compileSidecars: expected an array of TypedChannelConfig";
+    }
+    for (let i = 0; i < channels.length; i++) {
+        const c = channels[i];
+        if (!c || typeof c !== "object") {
+            return `compileSidecars: channels[${i}] is not an object`;
+        }
+        const obj = c;
+        if (typeof obj.name !== "string" || typeof obj.kind !== "string") {
+            return `compileSidecars: channels[${i}] missing string name/kind`;
+        }
+        if (!obj.scope || typeof obj.scope !== "object") {
+            return `compileSidecars: channels[${i}].scope is not an object`;
+        }
+    }
+    return null;
+}
+/**
+ * Compile an array of typed channel declarations into OpenShell policy YAML.
+ *
+ * @param channels  Flattened channel declarations from `.channels.json` sidecars.
+ * @param timestamp Epoch milliseconds for the audit log (caller-supplied; NOT hashed).
+ * @returns         CompilationResult — { success, policyYaml, policyHash, auditLog }
+ *                  on success, or { success: false, code, error } on failure.
+ */
+function compileSidecars(channels, timestamp) {
+    const validationError = validateInput(channels);
+    if (validationError) {
+        return { success: false, code: "invalid-input", error: validationError };
+    }
+    // Deep-freeze so no mapper can inadvertently mutate the shared input.
+    const frozen = deepFreeze(structuredClone(channels));
+    const readWritePaths = [];
+    const readOnlyPaths = [];
+    const networkPolicies = {};
+    const anomalies = [];
+    const skippedChannels = [];
+    let channelsProcessed = 0;
+    // Deterministic processing order: sort by (kind, name) so output is stable
+    // regardless of input array order.
+    const ordered = [...frozen].sort((a, b) => {
+        const ka = `${a.kind}/${a.name}`;
+        const kb = `${b.kind}/${b.name}`;
+        return ka < kb ? -1 : ka > kb ? 1 : 0;
+    });
+    for (const channel of ordered) {
+        const result = (0, mappings_1.mapChannel)(channel);
+        if ("skipped" in result) {
+            skippedChannels.push(result.reason);
+            continue;
+        }
+        channelsProcessed += 1;
+        if (result.readWritePaths)
+            readWritePaths.push(...result.readWritePaths);
+        if (result.readOnlyPaths)
+            readOnlyPaths.push(...result.readOnlyPaths);
+        for (const [key, policy] of Object.entries(result.networkPolicies)) {
+            if (networkPolicies[key] !== undefined) {
+                anomalies.push(`network policy name collision on "${key}" — overwriting`);
+            }
+            networkPolicies[key] = policy;
+        }
+        anomalies.push(...result.anomalies);
+    }
+    const policy = {
+        version: 1,
+        filesystem_policy: (0, mappings_1.buildFilesystem)(readWritePaths, readOnlyPaths),
+        landlock: { compatibility: "best_effort" },
+        process: { run_as_user: "sandbox", run_as_group: "sandbox" },
+        network_policies: networkPolicies,
+    };
+    // Header comments surface mapping limitations for the human reading the YAML.
+    const headerComments = [
+        "Generated by fractal-openshell-bridge. Alpha, AI-built, not human-reviewed.",
+        "Read this policy before applying it. Anomalies are documented inline.",
+        ...anomalies,
+    ];
+    let policyYaml;
+    try {
+        policyYaml = (0, serialize_1.serializePolicy)(policy, headerComments);
+    }
+    catch (err) {
+        return {
+            success: false,
+            code: "serialize-failed",
+            error: `YAML serialization failed: ${err.message}`,
+        };
+    }
+    // SHA-256 over the YAML string ONLY. The timestamp (and thus the audit log)
+    // is deliberately excluded so identical input yields an identical hash.
+    const policyHash = (0, crypto_1.createHash)("sha256").update(policyYaml, "utf8").digest("hex");
+    const auditLog = {
+        timestamp,
+        channelsProcessed,
+        skippedChannels,
+        anomaliesDetected: anomalies,
+    };
+    return { success: true, policyYaml, policyHash, auditLog };
+}
+var serialize_2 = require("./serialize");
+Object.defineProperty(exports, "serializePolicy", { enumerable: true, get: function () { return serialize_2.serializePolicy; } });
+var mappings_2 = require("./mappings");
+Object.defineProperty(exports, "mapChannel", { enumerable: true, get: function () { return mappings_2.mapChannel; } });
+Object.defineProperty(exports, "buildFilesystem", { enumerable: true, get: function () { return mappings_2.buildFilesystem; } });

package/dist/src/compiler/mappings.d.ts

@@ -0,0 +1,31 @@
+/**
+ * fractal-openshell-bridge — per-kind channel → OpenShell policy mapping
+ *
+ * Keepers: file, http, the 5 LLM channels, github, git, package.
+ *
+ * Architectural principle: a JS scope layer earns its keep when the platform
+ * has NO native privilege model. Channels that duplicate platform-native RBAC
+ * (postgres roles, stripe restricted keys, AWS IAM) are deliberately NOT
+ * mapped — they breed bypasses (see audit findings).
+ *
+ * Red-team corrections applied:
+ *   - github: path narrowing now preserves the operation suffix (/repos/{repo}/pulls,
+ *     not /repos/{repo}); one rule per (operation, repo).
+ *   - git + package: added as keepers (dropping them silently broke coding-agent
+ *     workflows; they have no strong native privilege model).
+ *   - binaries: configurable via scope.binaries; per-kind defaults.
+ */
+import type { TypedChannelConfig, FilesystemDef, NetworkPolicyRuleDef } from "./types";
+export interface MappingContribution {
+    readWritePaths?: string[];
+    readOnlyPaths?: string[];
+    networkPolicies: Record<string, NetworkPolicyRuleDef>;
+    anomalies: string[];
+}
+export interface MappingSkip {
+    skipped: true;
+    reason: string;
+}
+export type MappingResult = MappingContribution | MappingSkip;
+export declare function mapChannel(channel: TypedChannelConfig): MappingResult;
+export declare function buildFilesystem(readWrite: string[], readOnly: string[]): FilesystemDef;

package/dist/src/compiler/mappings.js

@@ -0,0 +1,316 @@
+"use strict";
+/**
+ * fractal-openshell-bridge — per-kind channel → OpenShell policy mapping
+ *
+ * Keepers: file, http, the 5 LLM channels, github, git, package.
+ *
+ * Architectural principle: a JS scope layer earns its keep when the platform
+ * has NO native privilege model. Channels that duplicate platform-native RBAC
+ * (postgres roles, stripe restricted keys, AWS IAM) are deliberately NOT
+ * mapped — they breed bypasses (see audit findings).
+ *
+ * Red-team corrections applied:
+ *   - github: path narrowing now preserves the operation suffix (/repos/{repo}/pulls,
+ *     not /repos/{repo}); one rule per (operation, repo).
+ *   - git + package: added as keepers (dropping them silently broke coding-agent
+ *     workflows; they have no strong native privilege model).
+ *   - binaries: configurable via scope.binaries; per-kind defaults.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mapChannel = mapChannel;
+exports.buildFilesystem = buildFilesystem;
+/** Default node binary path in the BYOC image (node:22-slim). */
+const DEFAULT_BINARY = "/usr/local/bin/node";
+/** LLM provider default API hosts (overridable via scope.baseUrl). */
+const LLM_HOSTS = {
+    anthropic: "api.anthropic.com",
+    openai: "api.openai.com",
+    "google-genai": "generativelanguage.googleapis.com",
+    cohere: "api.cohere.com",
+    mistral: "api.mistral.ai",
+};
+/** GitHub operation → HTTP method + path template (with /** repo placeholder). */
+const GITHUB_OP_MAP = {
+    createPR: { method: "POST", path: "/repos/**/pulls" },
+    mergePR: { method: "PUT", path: "/repos/**/pulls/*/merge" },
+    listPRs: { method: "GET", path: "/repos/**/pulls" },
+    getPR: { method: "GET", path: "/repos/**/pulls/*" },
+    createIssue: { method: "POST", path: "/repos/**/issues" },
+    listIssues: { method: "GET", path: "/repos/**/issues" },
+    getIssue: { method: "GET", path: "/repos/**/issues/*" },
+    commentOnIssue: { method: "POST", path: "/repos/**/issues/*/comments" },
+    closeIssue: { method: "PATCH", path: "/repos/**/issues/*" },
+    listRepos: { method: "GET", path: "/user/repos" },
+    getRepo: { method: "GET", path: "/repos/**" },
+    createRelease: { method: "POST", path: "/repos/**/releases" },
+};
+function str(v) {
+    return typeof v === "string" ? v : undefined;
+}
+function strArr(v) {
+    return Array.isArray(v) ? v.filter((x) => typeof x === "string") : [];
+}
+/** Resolve binaries: scope.binaries overrides the per-kind fallback. */
+function binariesFor(scope, fallback) {
+    const declared = strArr(scope.binaries);
+    return (declared.length > 0 ? declared : fallback).map((p) => ({ path: p }));
+}
+function hostFromBaseUrl(v) {
+    const u = str(v);
+    if (!u)
+        return undefined;
+    try {
+        return new URL(u).hostname;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Extract host from a git remote (https://, ssh://, or scp-like user@host:path). */
+function hostFromRemote(remote) {
+    try {
+        if (/^https?:\/\//.test(remote))
+            return new URL(remote).hostname;
+        if (/^ssh:\/\//.test(remote))
+            return new URL(remote).hostname;
+        // scp-like: [user@]host:path
+        const m = remote.match(/^([^/@]+@)?([^/:]+):/);
+        if (m)
+            return m[2];
+        // bare host
+        return new URL(`https://${remote}`).hostname;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Extract host from a package registry (URL or bare host). */
+function hostFromRegistry(reg) {
+    try {
+        return new URL(reg.startsWith("http") ? reg : `https://${reg}`).hostname;
+    }
+    catch {
+        return undefined;
+    }
+}
+function httpsEndpoint(host, rules, access) {
+    return {
+        host,
+        port: 443,
+        protocol: "rest",
+        tls: "terminate",
+        enforcement: "enforce",
+        ...(access ? { access } : {}),
+        rules,
+    };
+}
+function mapChannel(channel) {
+    const { kind, scope, name } = channel;
+    switch (kind) {
+        case "file": {
+            const allowedPaths = strArr(scope.allowedPaths);
+            const protectedPaths = strArr(scope.protectedPaths);
+            const anomalies = [];
+            if (protectedPaths.length > 0) {
+                anomalies.push(`file channel "${name}": protectedPaths ${JSON.stringify(protectedPaths)} cannot be expressed as a deny-list in OpenShell filesystem_policy. Ensure these paths are NOT granted write elsewhere; Landlock enforces the read_only/read_write split at the kernel level.`);
+            }
+            return { readWritePaths: allowedPaths, networkPolicies: {}, anomalies };
+        }
+        case "http": {
+            const allowedHosts = strArr(scope.allowedHosts);
+            const allowedMethods = strArr(scope.allowedMethods);
+            if (allowedHosts.length === 0) {
+                return { skipped: true, reason: `http channel "${name}" has no allowedHosts` };
+            }
+            const rules = allowedMethods.map((m) => ({
+                allow: { method: m.toUpperCase() },
+            }));
+            const endpoints = allowedHosts.map((h) => httpsEndpoint(h, rules));
+            return {
+                networkPolicies: {
+                    [`writ_http_${name}`]: {
+                        name: `writ_http_${name}`,
+                        endpoints,
+                        binaries: binariesFor(scope, [DEFAULT_BINARY]),
+                    },
+                },
+                anomalies: [],
+            };
+        }
+        case "anthropic":
+        case "openai":
+        case "google-genai":
+        case "cohere":
+        case "mistral": {
+            const defaultHost = LLM_HOSTS[kind];
+            const host = hostFromBaseUrl(scope.baseUrl) ?? defaultHost;
+            if (!host) {
+                return { skipped: true, reason: `${kind} channel "${name}": no host resolvable` };
+            }
+            const rules = [{ allow: { method: "POST", path: "/v1/**" } }];
+            return {
+                networkPolicies: {
+                    [`writ_${kind}_${name}`]: {
+                        name: `writ_${kind}_${name}`,
+                        endpoints: [httpsEndpoint(host, rules)],
+                        binaries: binariesFor(scope, [DEFAULT_BINARY]),
+                    },
+                },
+                anomalies: [
+                    `${kind} channel "${name}": allowedModels/maxTokensPerCall/rate limits are Fractal-enforced (app-semantic); OpenShell network policy only constrains host+method, not model/token semantics.`,
+                ],
+            };
+        }
+        case "github": {
+            const allowedRepos = strArr(scope.allowedRepos);
+            const allowedOperations = strArr(scope.allowedOperations);
+            const anomalies = [];
+            const rules = [];
+            const unmapped = [];
+            for (const op of allowedOperations) {
+                const m = GITHUB_OP_MAP[op];
+                if (!m) {
+                    unmapped.push(op);
+                    continue;
+                }
+                if (allowedRepos.length > 0) {
+                    // One rule per (operation, repo). Substitute /** with the repo,
+                    // PRESERVING the operation suffix (/repos/{repo}/pulls, not /repos/{repo}).
+                    for (const repo of allowedRepos) {
+                        rules.push({
+                            allow: { method: m.method, path: m.path.replace("/**", `/${repo}`) },
+                        });
+                    }
+                }
+                else {
+                    rules.push({ allow: { method: m.method, path: m.path } });
+                }
+            }
+            if (unmapped.length > 0) {
+                anomalies.push(`github channel "${name}": operations ${JSON.stringify(unmapped)} have no L7 method/path mapping; emitted rules cover only the mapped subset.`);
+            }
+            return {
+                networkPolicies: {
+                    [`writ_github_${name}`]: {
+                        name: `writ_github_${name}`,
+                        endpoints: [httpsEndpoint("api.github.com", rules, "read-only")],
+                        binaries: binariesFor(scope, [DEFAULT_BINARY, "/usr/bin/git", "/usr/local/bin/git"]),
+                    },
+                },
+                anomalies,
+            };
+        }
+        case "git": {
+            const remotes = strArr(scope.allowRemotes);
+            const hosts = [
+                ...new Set(remotes.map(hostFromRemote).filter((h) => h !== undefined)),
+            ];
+            if (hosts.length === 0) {
+                return { skipped: true, reason: `git channel "${name}": no allowRemotes hosts resolvable` };
+            }
+            const endpoints = hosts.map((h) => httpsEndpoint(h, [], "read-write"));
+            return {
+                networkPolicies: {
+                    [`writ_git_${name}`]: {
+                        name: `writ_git_${name}`,
+                        endpoints,
+                        binaries: binariesFor(scope, ["/usr/bin/git", "/usr/local/bin/git", DEFAULT_BINARY]),
+                    },
+                },
+                anomalies: [
+                    `git channel "${name}": git can exfiltrate via commit+push. openshell-prover will flag git as a credentialed L7-bypass binary — this is intentional; review the prover finding and ensure allowRemotes is tightly scoped.`,
+                ],
+            };
+        }
+        case "package": {
+            const registries = strArr(scope.allowedRegistries);
+            const hosts = [
+                ...new Set(registries.map(hostFromRegistry).filter((h) => h !== undefined)),
+            ];
+            if (hosts.length === 0) {
+                return {
+                    skipped: true,
+                    reason: `package channel "${name}": no allowedRegistries hosts resolvable`,
+                };
+            }
+            const endpoints = hosts.map((h) => httpsEndpoint(h, [], "read-write"));
+            return {
+                networkPolicies: {
+                    [`writ_package_${name}`]: {
+                        name: `writ_package_${name}`,
+                        endpoints,
+                        binaries: binariesFor(scope, [
+                            DEFAULT_BINARY,
+                            "/usr/bin/npm",
+                            "/usr/bin/pnpm",
+                            "/usr/bin/yarn",
+                            "/usr/bin/pip3",
+                            "/usr/bin/uv",
+                        ]),
+                    },
+                },
+                anomalies: [
+                    `package channel "${name}": lockfileEnforced/allowedPackages are Fractal-enforced (app-semantic); OpenShell network policy only constrains the registry host.`,
+                ],
+            };
+        }
+        default: {
+            const dropped = {
+                postgres: "read-only via SQL inspection is unsound — use a Postgres read-only role",
+                sqlite: "read-only via SQL inspection is unsound — use a read-only DB file/role",
+                stripe: "duplicates Stripe's restricted-key + permission-scope model",
+                "aws-s3": "duplicates AWS IAM — lean on roles, not JS bucket-scoping",
+                sqs: "duplicates AWS IAM",
+                docker: "native RBAC; JS re-scoping is a fragile duplicate",
+                kubernetes: "native RBAC; JS re-scoping is a fragile duplicate",
+                terraform: "native policy model; JS re-scoping is a fragile duplicate",
+                vault: "native policy model; JS re-scoping is a fragile duplicate",
+                "github-actions": "native RBAC; JS re-scoping is a fragile duplicate",
+                browser: "allowedHosts overlaps OpenShell network policy — redundant",
+                gitlab: "unaudited — not in initial bridge scope",
+                slack: "unaudited — not in initial bridge scope",
+                linear: "unaudited — not in initial bridge scope",
+                notion: "unaudited — not in initial bridge scope",
+                jira: "unaudited — not in initial bridge scope",
+                sentry: "unaudited — not in initial bridge scope",
+                datadog: "unaudited — not in initial bridge scope",
+                resend: "unaudited — not in initial bridge scope",
+                pinecone: "unaudited — not in initial bridge scope",
+                redactor: "pure data transform — no network/filesystem surface",
+                clock: "bounded time access — no network/filesystem surface",
+                billing: "internal metrics — no network/filesystem surface",
+                webhook: "inbound only — OpenShell governs outbound",
+                vitest: "local execution, networkMode: none by default",
+                jest: "local execution, networkMode: none by default",
+                pytest: "local execution, networkMode: none by default",
+                "go-test": "local execution, networkMode: none by default",
+                "cargo-test": "local execution, networkMode: none by default",
+                test: "local execution, networkMode: none by default",
+                build: "local execution — filesystem covered if it writes files",
+                process: "local execution — filesystem covered if it writes files",
+                search: "local execution — ripgrep over the workspace",
+                template: "local string rendering — no network/filesystem surface",
+                "gpu-inference": "managed via OpenShell's separate inference route system",
+            };
+            const reason = dropped[kind] ?? `unknown kind — not in the keeper set; skipped to avoid false assurance`;
+            return { skipped: true, reason: `${kind} channel "${name}": ${reason}` };
+        }
+    }
+}
+function buildFilesystem(readWrite, readOnly) {
+    const dedupe = (arr) => [...new Set(arr)].sort();
+    return {
+        include_workdir: true,
+        read_only: dedupe([
+            ...readOnly,
+            "/usr",
+            "/lib",
+            "/proc",
+            "/dev/urandom",
+            "/app",
+            "/etc",
+            "/var/log",
+        ]),
+        read_write: dedupe(readWrite),
+    };
+}

package/dist/src/compiler/serialize.d.ts

@@ -0,0 +1,23 @@
+/**
+ * fractal-openshell-bridge — deterministic YAML serializer
+ *
+ * A purpose-built emitter for the PolicyFile shape. Not a general YAML library.
+ * Determinism rules:
+ *   - Object keys emitted in lexicographic order.
+ *   - Order-irrelevant arrays (paths, hosts, ports) sorted before emission.
+ *   - Order-relevant arrays (L7 rules, where precedence can matter) preserved
+ *     in generation order — generation is itself deterministic (sorted inputs).
+ *   - Strings quoted only when they contain YAML-significant characters; bare
+ *     otherwise, so the output stays human-readable for manual eyeballing.
+ *   - No trailing whitespace; LF newlines; 2-space indent.
+ *
+ * Line length is kept under 120 where practical; scalar values that would
+ * exceed it are emitted on their own line.
+ */
+/**
+ * Serialize a PolicyFile to deterministic YAML. Header comments are prepended
+ * (mapping-limitation notes; the caller supplies them so the serializer stays
+ * shape-agnostic). The hash is computed over the returned string by the caller.
+ */
+export declare function serializePolicy(policy: PolicyFile, headerComments: string[]): string;
+import type { PolicyFile } from "./types";

package/dist/src/compiler/serialize.js

@@ -0,0 +1,119 @@
+"use strict";
+/**
+ * fractal-openshell-bridge — deterministic YAML serializer
+ *
+ * A purpose-built emitter for the PolicyFile shape. Not a general YAML library.
+ * Determinism rules:
+ *   - Object keys emitted in lexicographic order.
+ *   - Order-irrelevant arrays (paths, hosts, ports) sorted before emission.
+ *   - Order-relevant arrays (L7 rules, where precedence can matter) preserved
+ *     in generation order — generation is itself deterministic (sorted inputs).
+ *   - Strings quoted only when they contain YAML-significant characters; bare
+ *     otherwise, so the output stays human-readable for manual eyeballing.
+ *   - No trailing whitespace; LF newlines; 2-space indent.
+ *
+ * Line length is kept under 120 where practical; scalar values that would
+ * exceed it are emitted on their own line.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serializePolicy = serializePolicy;
+const INDENT = "  ";
+/** True if a string can be emitted bare (unquoted) in YAML. */
+function isBareSafe(s) {
+    if (s === "")
+        return false;
+    // Bare booleans/null/numbers must be quoted to preserve string type.
+    if (/^(true|false|null|yes|no|on|off|~)$/i.test(s))
+        return false;
+    if (/^-?\d+$/.test(s))
+        return false;
+    // Reject anything with YAML-significant characters.
+    if (/[:#{}\[\],&*!|>'"%@`]/.test(s))
+        return false;
+    if (/^\s|\s$/.test(s))
+        return false;
+    if (/^[-?]/.test(s))
+        return false;
+    return true;
+}
+function quoteString(s) {
+    // Double-quote; escape backslash and double-quote.
+    return `"${s.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+function emitScalar(value) {
+    if (value === null || value === undefined)
+        return "null";
+    if (typeof value === "boolean")
+        return value ? "true" : "false";
+    if (typeof value === "number")
+        return Number.isFinite(value) ? String(value) : "null";
+    if (typeof value === "string")
+        return isBareSafe(value) ? value : quoteString(value);
+    // Shouldn't reach here for scalars; stringify defensively.
+    return quoteString(String(value));
+}
+/** Sort an array of strings deterministically (order-irrelevant arrays). */
+function sortedStrings(arr) {
+    return [...arr].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+}
+/**
+ * Emit a value as YAML at the given indent depth. `topLevelComments` collects
+ * header comments (mapping-limitation notes) emitted before the document.
+ */
+function emitValue(value, depth) {
+    const pad = INDENT.repeat(depth);
+    if (Array.isArray(value)) {
+        if (value.length === 0)
+            return "[]";
+        // Arrays of strings → sort for determinism (paths, hosts). Arrays of
+        // objects (rules, endpoints) → preserve order; generation sorts inputs.
+        const allStrings = value.every((v) => typeof v === "string");
+        const items = allStrings ? sortedStrings(value) : value;
+        const itemIndent = INDENT.repeat(depth + 1);
+        return items
+            .map((item) => {
+            if (item === null || typeof item !== "object") {
+                // Scalar item → inline after the dash: "- /app"
+                return `${pad}- ${emitScalar(item)}`;
+            }
+            // Object/array item → emit at depth+1, then fold the first line up
+            // after the dash: "- path: x" or "- allow:\n    method: POST".
+            const itemStr = emitValue(item, depth + 1);
+            return `${pad}- ${itemStr.slice(itemIndent.length)}`;
+        })
+            .join("\n");
+    }
+    if (value && typeof value === "object") {
+        const obj = value;
+        const keys = Object.keys(obj).sort();
+        if (keys.length === 0)
+            return "{}";
+        return keys
+            .map((key) => {
+            const v = obj[key];
+            const vStr = emitValue(v, depth + 1);
+            // Inline scalar values: "key: val". Nested: "key:\n  ...".
+            if (v === null ||
+                typeof v !== "object" ||
+                (Array.isArray(v) && v.length === 0) ||
+                (typeof v === "object" && Object.keys(v).length === 0)) {
+                return `${pad}${key}: ${emitScalar(v)}`;
+            }
+            return `${pad}${key}:\n${vStr}`;
+        })
+            .join("\n");
+    }
+    return `${pad}${emitScalar(value)}`;
+}
+/**
+ * Serialize a PolicyFile to deterministic YAML. Header comments are prepended
+ * (mapping-limitation notes; the caller supplies them so the serializer stays
+ * shape-agnostic). The hash is computed over the returned string by the caller.
+ */
+function serializePolicy(policy, headerComments) {
+    const body = emitValue(policy, 0);
+    const header = headerComments.length > 0
+        ? headerComments.map((c) => `# ${c}`).join("\n") + "\n\n"
+        : "";
+    return `${header}${body}\n`;
+}