arkgate 4.8.23 → 4.8.24

package/bin/lib/config-contract.mjs

@@ -9,6 +9,7 @@
  */
 
 import { ARK_ORDER_SCHEMA_DEF, ARK_RUN_SCHEMA_DEF, defaultedArkOrder, defaultedArkRun, validateArkOrderExtra, validateArkRunExtra, } from './config-extras.mjs';
+import { CHILD_SLICES_SCHEMA_DEF, SHARED_IMPORTS_SLICE_SCHEMA_DEF, validateSliceContract, } from './config-contract-slices.mjs';
 import { canonicalStewardId } from './team-parliament.mjs';
 /** Current published ark.config.json schema version (ADR 0027: 1.3 adds optional arkOrder). */
 export const ARK_CONFIG_SCHEMA_VERSION = '1.3';
@@ -217,7 +218,7 @@ export const ARK_CONFIG_SCHEMA = {
                 sliceIdentity: {
                     type: 'string',
                     enum: ['path', 'stars'],
-                    description: 'How a starred sliceFolders prefix is named. Absent and path keep today\'s ids (every literal and star binding). stars keeps the last literal plus the star bindings, so parallel trees share one feature id. Bare names are unchanged.',
+                    description: 'How a starred sliceFolders prefix is named. Absent and path keep today\'s ids (every literal and star binding). stars keeps the last literal plus every star binding (a star before the last literal is kept too), so parallel trees share one feature id. Bare names are unchanged.',
                 },
                 sharedRoots: { ...stringArraySchema, minItems: 1 },
                 allowedCrossSlice: {
@@ -233,69 +234,8 @@ export const ARK_CONFIG_SCHEMA = {
                         },
                     },
                 },
-                sharedImportsSlice: {
-                    type: 'string',
-                    enum: ['deny', 'deny-cross-parent'],
-                    description: 'deny blocks every shared-root import of a slice. deny-cross-parent leaves that hop as a warning and, in ark-check and CI only, reports a slice that reaches another universe through a shared root. The write hook and ESLint see one edge and do not block it. arkgate 4.8.22 and older reject deny-cross-parent.',
-                },
-                childSlices: {
-                    type: 'object',
-                    additionalProperties: false,
-                    required: ['sliceFolders'],
-                    description: 'Optional inner wall under this rule. Absent keeps today\'s universe wall. sliceFolders names children. commonFolders and flat files are universe common. siblings is "deny" (default), "advisory", or { default, enforce }. parentMayImportChild defaults to false. allowedCrossSlice may use a whole-segment *. It clears only a sibling crossing. Cross-parent has no advisory knob. arkgate 4.8.22 and older reject this key. A build that still rejects unknown childSlices fields rejects allowedCrossSlice at config load. A build that still types siblings as a string enum rejects the object at config load.',
-                    properties: {
-                        sliceFolders: { ...stringArraySchema, minItems: 1 },
-                        sliceIdentity: {
-                            type: 'string',
-                            enum: ['path', 'stars'],
-                        },
-                        commonFolders: { ...stringArraySchema, minItems: 1 },
-                        siblings: {
-                            description: '"deny" or "advisory", or { default, enforce } so listed subtrees are errors while the default stays advisory. A string-enum build rejects the object at config load (must be one of deny, advisory).',
-                            oneOf: [
-                                { type: 'string', enum: ['deny', 'advisory'] },
-                                {
-                                    type: 'object',
-                                    additionalProperties: false,
-                                    required: ['default'],
-                                    properties: {
-                                        default: { type: 'string', enum: ['deny', 'advisory'] },
-                                        enforce: { ...stringArraySchema },
-                                    },
-                                },
-                            ],
-                        },
-                        parentMayImportChild: { type: 'boolean' },
-                        sliceAliases: {
-                            type: 'array',
-                            minItems: 1,
-                            description: 'Maps a source path glob onto a child slice id (universe id plus one child segment) so files outside the slice trees take that universe and child for both walls. A bare name, a universe id alone, an unknown universe, and a wildcard in to are rejected. The glob may not overlap a slice folder, and two aliases may not match the same file. Doctor lists each alias as an owed move. A build that rejects unknown childSlices fields fails at config load (unknown field). arkgate 4.8.22 and older reject childSlices.',
-                            items: {
-                                type: 'object',
-                                additionalProperties: false,
-                                required: ['from', 'to'],
-                                properties: {
-                                    from: { type: 'string', minLength: 1 },
-                                    to: { type: 'string', minLength: 1 },
-                                },
-                            },
-                        },
-                        allowedCrossSlice: {
-                            type: 'array',
-                            minItems: 1,
-                            description: 'Directed child-slice allowances. * matches one whole path segment (features/projects/*). ** and a partial segment are rejected. A bare name is rejected. This list clears only CROSS_SIBLING_SLICE. It cannot clear CROSS_PARENT_SLICE or CROSS_PARENT_VIA_SHARED. The universe allowedCrossSlice still treats * as a literal. A build that rejects unknown childSlices fields fails at config load (unknown field).',
-                            items: {
-                                type: 'object',
-                                additionalProperties: false,
-                                required: ['from', 'to'],
-                                properties: {
-                                    from: { type: 'string', minLength: 1 },
-                                    to: { type: 'string', minLength: 1 },
-                                },
-                            },
-                        },
-                    },
-                },
+                sharedImportsSlice: SHARED_IMPORTS_SLICE_SCHEMA_DEF,
+                childSlices: CHILD_SLICES_SCHEMA_DEF,
             },
         },
         safety: {
@@ -457,420 +397,6 @@ function validateNode(value, schema, path, root, issues) {
         }
     }
 }
-const SIBLING_MODES = ['deny', 'advisory'];
-/**
- * String enum builds reject this object before they reach a decision.
- * The message names both forms so a bad value is obvious at config load.
- */
-const SIBLINGS_FORM_MESSAGE = 'must be "deny", "advisory", or { "default": "deny" | "advisory", "enforce": ["<child id or subtree path>"] }';
-function validateChildSliceSiblings(candidate, issues) {
-    const rules = candidate.rules;
-    if (!Array.isArray(rules))
-        return;
-    rules.forEach((rule, index) => {
-        if (!isObject(rule))
-            return;
-        const child = rule.childSlices;
-        if (!isObject(child) || child.siblings === undefined)
-            return;
-        const siblings = child.siblings;
-        const path = `$.rules[${index}].childSlices.siblings`;
-        if (typeof siblings === 'string') {
-            if (!SIBLING_MODES.includes(siblings)) {
-                issues.push({ path, message: SIBLINGS_FORM_MESSAGE });
-            }
-            return;
-        }
-        if (!isObject(siblings)) {
-            issues.push({ path, message: SIBLINGS_FORM_MESSAGE });
-            return;
-        }
-        for (const key of Object.keys(siblings)) {
-            if (key !== 'default' && key !== 'enforce') {
-                issues.push({ path: propertyPath(path, key), message: 'unknown field' });
-            }
-        }
-        if (siblings.default === undefined) {
-            issues.push({ path: `${path}.default`, message: 'is required' });
-        }
-        else if (siblings.default !== 'deny' && siblings.default !== 'advisory') {
-            issues.push({ path: `${path}.default`, message: 'must be deny or advisory' });
-        }
-        if (siblings.enforce === undefined)
-            return;
-        if (!Array.isArray(siblings.enforce)) {
-            issues.push({
-                path: `${path}.enforce`,
-                message: 'must be an array of child slice ids or subtree paths',
-            });
-            return;
-        }
-        const seen = new Set();
-        siblings.enforce.forEach((entry, entryIndex) => {
-            const entryPath = `${path}.enforce[${entryIndex}]`;
-            if (typeof entry !== 'string' || entry.trim().length === 0) {
-                issues.push({ path: entryPath, message: 'must be a non-empty child slice id or subtree path' });
-                return;
-            }
-            const normalized = trimTrailingSlashes(entry.trim().replace(/\\/g, '/'));
-            if (normalized.split('/').some((part) => part.length === 0 || part === '.' || part === '..')) {
-                issues.push({ path: entryPath, message: 'must be a child slice id or subtree path without . or ..' });
-                return;
-            }
-            if (normalized.includes('*')) {
-                issues.push({
-                    path: entryPath,
-                    message: 'must be a child slice id or subtree path. * is not a wildcard on siblings.enforce',
-                });
-                return;
-            }
-            if (seen.has(normalized)) {
-                issues.push({ path: entryPath, message: 'duplicate enforce entry' });
-                return;
-            }
-            seen.add(normalized);
-        });
-    });
-}
-const BARE_CHILD_CROSS_SLICE = 'must be a slice id with a slash. A bare name is ambiguous across universes.';
-const WHOLE_SEGMENT_STAR = '* matches one whole path segment. ** and a partial segment are not wildcards.';
-/**
- * Whole-segment `*` is legal only on this list. A bare name is rejected.
- * The universe allowedCrossSlice is not checked here and still treats `*` as a literal.
- */
-function childCrossSlicePatternIssue(raw) {
-    const trimmed = trimTrailingSlashes(raw.trim().replace(/\\/g, '/'));
-    if (trimmed.length === 0)
-        return 'must be a non-empty slice id';
-    if (!trimmed.includes('/'))
-        return BARE_CHILD_CROSS_SLICE;
-    const parts = trimmed.split('/');
-    for (const part of parts) {
-        if (part.length === 0 || part === '.' || part === '..') {
-            return 'must be a slice id without empty, . or .. segments';
-        }
-        if (part.includes('*') && part !== '*')
-            return WHOLE_SEGMENT_STAR;
-    }
-    return null;
-}
-function childCrossSlicePatternKey(raw) {
-    return trimTrailingSlashes(raw.trim().replace(/\\/g, '/')).toLowerCase();
-}
-function validateChildSliceAllowedCrossSlice(candidate, issues) {
-    const rules = candidate.rules;
-    if (!Array.isArray(rules))
-        return;
-    rules.forEach((rule, index) => {
-        if (!isObject(rule))
-            return;
-        const child = rule.childSlices;
-        if (!isObject(child) || child.allowedCrossSlice === undefined)
-            return;
-        const edges = child.allowedCrossSlice;
-        const path = `$.rules[${index}].childSlices.allowedCrossSlice`;
-        if (!Array.isArray(edges)) {
-            issues.push({ path, message: 'must be an array of { from, to } child slice ids' });
-            return;
-        }
-        const seen = new Set();
-        edges.forEach((edge, edgeIndex) => {
-            const edgePath = `${path}[${edgeIndex}]`;
-            if (!isObject(edge)) {
-                issues.push({ path: edgePath, message: 'must be an object with from and to' });
-                return;
-            }
-            for (const key of Object.keys(edge)) {
-                if (key !== 'from' && key !== 'to') {
-                    issues.push({ path: propertyPath(edgePath, key), message: 'unknown field' });
-                }
-            }
-            for (const side of ['from', 'to']) {
-                const value = edge[side];
-                const sidePath = `${edgePath}.${side}`;
-                if (typeof value !== 'string' || value.trim().length === 0) {
-                    issues.push({ path: sidePath, message: 'must be a non-empty slice id' });
-                    continue;
-                }
-                const issue = childCrossSlicePatternIssue(value);
-                if (issue)
-                    issues.push({ path: sidePath, message: issue });
-            }
-            if (typeof edge.from !== 'string' || typeof edge.to !== 'string')
-                return;
-            const key = `${childCrossSlicePatternKey(edge.from)}\0${childCrossSlicePatternKey(edge.to)}`;
-            if (!key.startsWith('\0') && !key.endsWith('\0')) {
-                if (seen.has(key)) {
-                    issues.push({ path: edgePath, message: 'duplicate child slice allowance' });
-                    return;
-                }
-                seen.add(key);
-            }
-        });
-    });
-}
-const ALIAS_TARGET_MESSAGE = 'must be a child of an existing universe (the universe id this rule already names, plus one child segment). A bare name, a universe id alone, an unknown universe, and a wildcard are rejected.';
-const ALIAS_OVERLAP_MESSAGE = 'overlaps a slice folder. An alias covers only files outside the slice trees.';
-const ALIAS_SAME_FILE_MESSAGE = 'two slice aliases match the same file';
-function aliasPathSegments(raw) {
-    return trimTrailingSlashes(raw.trim().replace(/\\/g, '/')).toLowerCase().split('/').filter((part) => part.length > 0);
-}
-function concreteGlobPrefix(segments) {
-    const prefix = [];
-    for (const segment of segments) {
-        if (segment.includes('*'))
-            break;
-        prefix.push(segment);
-    }
-    return prefix;
-}
-function segmentsArePrefix(prefix, full) {
-    if (prefix.length > full.length)
-        return false;
-    for (let index = 0; index < prefix.length; index += 1) {
-        if (prefix[index] !== full[index])
-            return false;
-    }
-    return true;
-}
-function anchoredSlicePrefix(entry) {
-    const segments = entry.split(/[/\\]/).filter(Boolean).map((part) => part.toLowerCase());
-    if (segments.length < 2 || segments[0] === '*' || segments[0] === '**')
-        return null;
-    if (!segments.some((part) => part === '*'))
-        return null;
-    const prefix = [];
-    for (const segment of segments) {
-        if (segment === '*' || segment === '**')
-            break;
-        if (segment.includes('*'))
-            return null;
-        prefix.push(segment);
-    }
-    return prefix.length > 0 ? prefix : null;
-}
-/** Trailing ** does not invent a slice-folder name the glob does not already reach. */
-function globOverlapsAnchored(glob, patternPrefix) {
-    const prefix = concreteGlobPrefix(glob);
-    const wild = prefix.length < glob.length;
-    const rooted = prefix[0] === 'src' || prefix[0] === 'app' ? prefix.slice(1) : prefix;
-    if (segmentsArePrefix(patternPrefix, prefix) || segmentsArePrefix(patternPrefix, rooted))
-        return true;
-    if (!wild)
-        return false;
-    return ((segmentsArePrefix(prefix, patternPrefix) && prefix.length < patternPrefix.length) ||
-        (segmentsArePrefix(prefix, ['src', ...patternPrefix]) && prefix.length < patternPrefix.length + 1) ||
-        (segmentsArePrefix(prefix, ['app', ...patternPrefix]) && prefix.length < patternPrefix.length + 1));
-}
-function globOverlapsBare(glob, name) {
-    for (let index = 0; index < glob.length; index += 1) {
-        if (glob[index] !== name && glob[index] !== '*')
-            continue;
-        const rest = glob.slice(index + 1);
-        if (rest.length >= 2)
-            return true;
-        if (rest.some((segment) => segment === '*' || segment === '**'))
-            return true;
-    }
-    const prefix = concreteGlobPrefix(glob);
-    return (prefix.length < glob.length &&
-        (prefix.length === 0 || (prefix.length === 1 && (prefix[0] === 'src' || prefix[0] === 'app'))));
-}
-function globOverlapsSliceEntry(glob, entry) {
-    const segments = entry.split(/[/\\]/).filter(Boolean).map((part) => part.toLowerCase());
-    if (segments.length === 1 && segments[0] && !segments[0].includes('*')) {
-        return globOverlapsBare(glob, segments[0]);
-    }
-    const prefix = anchoredSlicePrefix(entry);
-    return prefix ? globOverlapsAnchored(glob, prefix) : false;
-}
-function aliasGlobIssue(raw) {
-    const trimmed = trimTrailingSlashes(raw.trim().replace(/\\/g, '/'));
-    if (trimmed.length === 0)
-        return 'must be a non-empty path glob';
-    if (trimmed === '*' || trimmed === '**')
-        return 'must not cover the whole tree';
-    for (const part of trimmed.split('/')) {
-        if (part.length === 0 || part === '.' || part === '..') {
-            return 'must be a path glob without empty, . or .. segments';
-        }
-        if (part === '*' || part === '**')
-            continue;
-        if (part.includes('*') || part.includes('?') || part.includes('{') || part.includes('[')) {
-            return '* matches one whole path segment. ** is a whole segment. A partial segment is not a wildcard.';
-        }
-    }
-    return null;
-}
-function universeShapes(folders, identity) {
-    const shapes = [];
-    if (!Array.isArray(folders))
-        return shapes;
-    const stars = identity === 'stars';
-    for (const raw of folders) {
-        if (typeof raw !== 'string' || raw.length === 0)
-            continue;
-        const segments = raw.split(/[/\\]/).filter(Boolean).map((part) => part.toLowerCase());
-        if (segments.length === 1 && segments[0] && !segments[0].includes('*')) {
-            shapes.push({ literals: [segments[0], null] });
-            continue;
-        }
-        if (segments.some((part) => part === '**' || (part.includes('*') && part !== '*')))
-            continue;
-        if (!segments.includes('*'))
-            continue;
-        if (stars) {
-            let lastLiteral = -1;
-            for (let index = 0; index < segments.length; index += 1) {
-                if (segments[index] !== '*')
-                    lastLiteral = index;
-            }
-            if (lastLiteral < 0)
-                continue;
-            shapes.push({
-                literals: segments.slice(lastLiteral).map((part) => (part === '*' ? null : part)),
-            });
-            continue;
-        }
-        shapes.push({ literals: segments.map((part) => (part === '*' ? null : part)) });
-    }
-    return shapes;
-}
-function shapeMatches(shape, segments) {
-    if (shape.literals.length !== segments.length)
-        return false;
-    return shape.literals.every((literal, index) => literal === null || literal === segments[index]);
-}
-function aliasTargetIssue(raw, shapes) {
-    const trimmed = trimTrailingSlashes(raw.trim().replace(/\\/g, '/'));
-    if (trimmed.length === 0 || trimmed.split('/').some((part) => part.length === 0 || part === '.' || part === '..')) {
-        return ALIAS_TARGET_MESSAGE;
-    }
-    if (trimmed.includes('*') || !trimmed.includes('/'))
-        return ALIAS_TARGET_MESSAGE;
-    const parts = trimmed.split('/').map((part) => part.toLowerCase());
-    if (shapes.length === 0)
-        return ALIAS_TARGET_MESSAGE;
-    if (shapes.some((shape) => shapeMatches(shape, parts)))
-        return ALIAS_TARGET_MESSAGE;
-    if (shapes.some((shape) => shapeMatches(shape, parts.slice(0, -1))))
-        return null;
-    return ALIAS_TARGET_MESSAGE;
-}
-/** A leading src/ or app/ is optional at match time, so both spellings are one glob. */
-function aliasGlobVariants(segments) {
-    const head = segments[0];
-    if ((head === 'src' || head === 'app') && segments.length > 1)
-        return [segments, segments.slice(1)];
-    return [segments];
-}
-function aliasesCanMatchSameFile(left, right) {
-    const leftVariants = aliasGlobVariants(left);
-    const rightVariants = aliasGlobVariants(right);
-    for (const a of leftVariants) {
-        if (globsCanMatchSame(a, right, 0, 0, new Map()))
-            return true;
-    }
-    for (const b of rightVariants) {
-        if (globsCanMatchSame(left, b, 0, 0, new Map()))
-            return true;
-    }
-    return false;
-}
-function globsCanMatchSame(left, right, i, j, memo) {
-    const key = `${i}:${j}`;
-    const cached = memo.get(key);
-    if (cached !== undefined)
-        return cached;
-    let matched = false;
-    if (i === left.length && j === right.length)
-        matched = true;
-    else if (i < left.length && left[i] === '**') {
-        matched =
-            globsCanMatchSame(left, right, i + 1, j, memo) ||
-                (j < right.length && globsCanMatchSame(left, right, i, j + 1, memo));
-    }
-    else if (j < right.length && right[j] === '**') {
-        matched =
-            globsCanMatchSame(left, right, i, j + 1, memo) ||
-                (i < left.length && globsCanMatchSame(left, right, i + 1, j, memo));
-    }
-    else if (i < left.length && j < right.length) {
-        const a = left[i];
-        const b = right[j];
-        if (a === b || a === '*' || b === '*')
-            matched = globsCanMatchSame(left, right, i + 1, j + 1, memo);
-    }
-    memo.set(key, matched);
-    return matched;
-}
-function validateChildSliceAliases(candidate, issues) {
-    const rules = candidate.rules;
-    if (!Array.isArray(rules))
-        return;
-    rules.forEach((rule, index) => {
-        if (!isObject(rule))
-            return;
-        const child = rule.childSlices;
-        if (!isObject(child) || child.sliceAliases === undefined)
-            return;
-        const aliases = child.sliceAliases;
-        const path = `$.rules[${index}].childSlices.sliceAliases`;
-        if (!Array.isArray(aliases)) {
-            issues.push({ path, message: 'must be an array of { from, to } slice aliases' });
-            return;
-        }
-        const shapes = universeShapes(rule.sliceFolders, rule.sliceIdentity);
-        const sliceEntries = [
-            ...(Array.isArray(rule.sliceFolders) ? rule.sliceFolders : []),
-            ...(Array.isArray(child.sliceFolders) ? child.sliceFolders : []),
-        ].filter((entry) => typeof entry === 'string' && entry.length > 0);
-        const globs = [];
-        aliases.forEach((alias, aliasIndex) => {
-            const aliasPath = `${path}[${aliasIndex}]`;
-            if (!isObject(alias)) {
-                issues.push({ path: aliasPath, message: 'must be an object with from and to' });
-                return;
-            }
-            for (const key of Object.keys(alias)) {
-                if (key !== 'from' && key !== 'to') {
-                    issues.push({ path: propertyPath(aliasPath, key), message: 'unknown field' });
-                }
-            }
-            const from = alias.from;
-            const to = alias.to;
-            if (typeof from !== 'string' || from.trim().length === 0) {
-                issues.push({ path: `${aliasPath}.from`, message: 'must be a non-empty path glob' });
-            }
-            else {
-                const issue = aliasGlobIssue(from);
-                if (issue)
-                    issues.push({ path: `${aliasPath}.from`, message: issue });
-                else {
-                    const segments = aliasPathSegments(from);
-                    if (sliceEntries.some((entry) => globOverlapsSliceEntry(segments, entry))) {
-                        issues.push({ path: `${aliasPath}.from`, message: ALIAS_OVERLAP_MESSAGE });
-                    }
-                    for (const previous of globs) {
-                        if (aliasesCanMatchSameFile(previous, segments)) {
-                            issues.push({ path: aliasPath, message: ALIAS_SAME_FILE_MESSAGE });
-                            break;
-                        }
-                    }
-                    globs.push(segments);
-                }
-            }
-            if (typeof to !== 'string' || to.trim().length === 0) {
-                issues.push({ path: `${aliasPath}.to`, message: ALIAS_TARGET_MESSAGE });
-            }
-            else {
-                const issue = aliasTargetIssue(to, shapes);
-                if (issue)
-                    issues.push({ path: `${aliasPath}.to`, message: issue });
-            }
-        });
-    });
-}
 function validateLayerOwners(candidate, issues) {
     const layers = candidate.layers;
     if (!Array.isArray(layers))
@@ -1001,9 +527,7 @@ export function loadArkConfigContract(input, source = 'ark.config.json') {
     validateArkRunExtra(candidate, issues);
     validateArkOrderExtra(candidate, issues);
     validateLayerOwners(candidate, issues);
-    validateChildSliceSiblings(candidate, issues);
-    validateChildSliceAllowedCrossSlice(candidate, issues);
-    validateChildSliceAliases(candidate, issues);
+    validateSliceContract(candidate, issues);
     if (issues.length > 0)
         throw new ArkConfigValidationError(source, issues);
     return { config: candidate, migratedFrom };
@@ -1036,15 +560,3 @@ export function withArkConfigMetadata(config) {
     }
     return result;
 }
-/**
- * Trim trailing slashes without a regex.
- *
- * `/\/+$/` is a polynomial ReDoS on a value that comes from the repo's own
- * contract but is still library input. A scan is linear and says the same thing.
- */
-function trimTrailingSlashes(value) {
-    let end = value.length;
-    while (end > 0 && value[end - 1] === '/')
-        end -= 1;
-    return value.slice(0, end);
-}

package/bin/lib/config-warnings.mjs

@@ -59,3 +59,35 @@ export function collectConfigWarnings(root, config, files, rules, manifest) {
     files: files.map((file) => normalize(path.relative(root, file))),
   });
 }
+
+/**
+ * Machine-readable refusal for an invalid contract under `--json` / `--doctor --json`.
+ * The human message still goes to stderr; stdout must never be empty for JSON consumers.
+ */
+
+/**
+ * @param {unknown} error
+ * @param {string[]} argv
+ * @returns {string|null} JSON line for stdout, or null when not a config-contract error / not --json
+ */
+export function configInvalidJsonEnvelope(error, argv) {
+  if (!argv.includes('--json')) return null;
+  const e = /** @type {{ name?: string, issues?: Array<{path: string, message: string}>, source?: string }} */ (error);
+  if (e?.name !== 'ArkConfigValidationError' || !Array.isArray(e.issues)) {
+    // Any other fatal error still answers --json with JSON (exit 2 stays the caller's job),
+    // so a CI step that parses stdout never sees an empty or plain-text body.
+    const message = error instanceof Error ? error.message : String(error);
+    const policyBase = /^(Cannot (read|resolve) policy base|Policy base )/.test(message);
+    return JSON.stringify({
+      ok: false,
+      error: policyBase ? 'POLICY_BASE_UNREADABLE' : 'CHECK_ERROR',
+      message,
+    });
+  }
+  return JSON.stringify({
+    ok: false,
+    error: 'CONFIG_INVALID',
+    configPath: e.source,
+    messages: e.issues.map((issue) => `${issue.path}: ${issue.message}`),
+  });
+}

package/bin/lib/dashboard-cli.mjs

@@ -0,0 +1,62 @@
+/**
+ * Shared, pure helpers for the observability dashboard CLI (`ark-dashboard`,
+ * `arkgate-dashboard`, and the `ark dashboard` passthrough). No I/O here.
+ */
+
+export const DASHBOARD_DEFAULT_INTERVAL_MS = 2000;
+export const DASHBOARD_DEFAULT_TIMEOUT_MS = 5000;
+export const DASHBOARD_DEFAULT_URL = 'http://127.0.0.1:3000/snapshot';
+export const DASHBOARD_MIN_MS = 200;
+export const DASHBOARD_MAX_MS = 60_000;
+
+export const DASHBOARD_HELP = `arkgate-dashboard (alias ark-dashboard, ark dashboard) — observability TUI.
+Usage: arkgate-dashboard [--url <inspector-url>] [--interval <ms>] [--timeout <ms>] [--once]
+Polls an ArkRun inspector; it does not start the kernel.
+
+  -u, --url <url>        Inspector URL: handle.url (root) or handle.snapshotUrl.
+                         Default: $ARK_DASHBOARD_URL, else ${DASHBOARD_DEFAULT_URL}.
+                         startInspector() binds a random port unless you pass
+                         { port }, so pass the URL your app printed.
+  -i, --interval <ms>    Poll interval, clamped to ${DASHBOARD_MIN_MS}-${DASHBOARD_MAX_MS} (default ${DASHBOARD_DEFAULT_INTERVAL_MS}).
+  -t, --timeout <ms>     Fetch timeout, clamped to ${DASHBOARD_MIN_MS}-${DASHBOARD_MAX_MS} (default ${DASHBOARD_DEFAULT_TIMEOUT_MS}).
+      --once             Render one frame and exit (non-zero when the kernel is unreachable).
+  -h, --help             Show this help.
+  -v, --version          Print the arkgate version.`;
+
+export const DASHBOARD_EPHEMERAL_PORT_HINT =
+  'Hint: startInspector() binds a random port by default (port 0). Pass --url <handle.url> ' +
+  '(printed by your app), set ARK_DASHBOARD_URL, or start the inspector with startInspector({ port: 3000 }).';
+
+/**
+ * Clamp a millisecond flag into [min, max]. Non-numeric input uses the default.
+ * @param {string | undefined} raw
+ * @param {number} fallback
+ */
+export function clampDashboardMs(raw, fallback) {
+  if (raw === undefined || raw === null || String(raw).trim() === '') return fallback;
+  const parsed = Number.parseInt(String(raw), 10);
+  if (!Number.isFinite(parsed)) return fallback;
+  return Math.min(DASHBOARD_MAX_MS, Math.max(DASHBOARD_MIN_MS, parsed));
+}
+
+/**
+ * Derive a sibling inspector route (`/outbox`, `/workflows`) from the URL the
+ * user passed. Accepts the inspector root (`handle.url`, with or without a
+ * trailing slash), `/snapshot`, `/snapshot/`, and prefix mounts (`/x/snapshot`).
+ * @param {string} inspectorUrl
+ * @param {string} suffix e.g. '/outbox'
+ * @returns {string | null}
+ */
+export function dashboardSiblingUrl(inspectorUrl, suffix) {
+  try {
+    const u = new URL(inspectorUrl);
+    let basePath = u.pathname.replace(/\/+$/, '');
+    if (basePath.endsWith('/snapshot')) basePath = basePath.slice(0, -'/snapshot'.length);
+    u.pathname = `${basePath}${suffix}`;
+    u.search = '';
+    u.hash = '';
+    return u.toString();
+  } catch {
+    return null;
+  }
+}