@phyzess/pappra 0.0.0-stage → 0.1.0-beta.2

package/dist/collab/canonical.d.ts

@@ -0,0 +1,26 @@
+import type { Resource, ResourceInput } from './types.js';
+export declare const RESOURCE_KINDS: readonly string[];
+/**
+ * Resolve the longest existing ancestor with realpath and append the not-yet-existing
+ * suffix. Symlink aliases therefore collapse to one key. The suffix keeps the caller's
+ * spelling, so a differently-cased non-existent target is not normalised.
+ */
+export declare function canonicalizeTarget(input: string): {
+    path: string;
+    existing: boolean;
+    nearest_ancestor: string;
+};
+/** `same`, `ancestor`, `descendant` or `disjoint` on path-segment boundaries. */
+export declare function pathRelation(left: string, right: string): "ancestor" | "descendant" | "disjoint" | "same";
+export declare function pathsOverlap(left: string, right: string): boolean;
+/**
+ * Build the canonical descriptor for one requested resource.
+ * Input: {kind?, path?, port?, value?}. Unknown kinds are rejected rather than guessed.
+ */
+export declare function describeResource(input: ResourceInput): Resource;
+/**
+ * Overlap between two claims. Path-like kinds compare on canonical paths; opaque kinds
+ * (ports, processes) only on exact keys. `port:` and `path:` never overlap.
+ */
+export declare function claimsOverlap(left: Resource, right: Resource): boolean;
+export declare function opaqueKey(prefix: string, value: unknown): string;

package/dist/collab/canonical.js

@@ -0,0 +1,136 @@
+import { errorCode } from './validation.js';
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+// Resource identity and path canonicalisation. Two claims overlap only when their
+// canonical paths are equal or one contains the other on a path-segment boundary,
+// so `repo-a` and `repo-ab` are never treated as nested.
+const PATH_KINDS = new Set([
+    'path',
+    'git-index',
+    'git-head',
+    'git-common-dir',
+    'build-cache',
+    'file',
+]);
+const OPAQUE_KINDS = new Set(['port', 'opaque', 'process']);
+export const RESOURCE_KINDS = Object.freeze([...PATH_KINDS, ...OPAQUE_KINDS].sort());
+/**
+ * Resolve the longest existing ancestor with realpath and append the not-yet-existing
+ * suffix. Symlink aliases therefore collapse to one key. The suffix keeps the caller's
+ * spelling, so a differently-cased non-existent target is not normalised.
+ */
+export function canonicalizeTarget(input) {
+    if (typeof input !== 'string' || input.trim().length === 0)
+        throw new Error('Resource path must be a non-empty string');
+    if (!path.isAbsolute(input))
+        throw new Error('Resource path must be absolute');
+    const missing = [];
+    let probe = path.normalize(input);
+    for (;;) {
+        try {
+            const real = fs.realpathSync(probe);
+            return {
+                path: path.join(real, ...missing.slice().reverse()),
+                existing: missing.length === 0,
+                nearest_ancestor: real,
+            };
+        }
+        catch (error) {
+            if (errorCode(error) !== 'ENOENT' && errorCode(error) !== 'ENOTDIR')
+                throw new Error(`Cannot resolve resource path: ${errorCode(error)}`);
+            const parent = path.dirname(probe);
+            if (parent === probe)
+                throw new Error('Resource path has no existing ancestor');
+            missing.push(path.basename(probe));
+            probe = parent;
+        }
+    }
+}
+/** `same`, `ancestor`, `descendant` or `disjoint` on path-segment boundaries. */
+export function pathRelation(left, right) {
+    if (left === right)
+        return 'same';
+    const a = left.split(path.sep).filter(Boolean);
+    const b = right.split(path.sep).filter(Boolean);
+    const shared = Math.min(a.length, b.length);
+    for (let index = 0; index < shared; index += 1) {
+        if (a[index] !== b[index])
+            return 'disjoint';
+    }
+    return a.length < b.length ? 'ancestor' : 'descendant';
+}
+export function pathsOverlap(left, right) {
+    return pathRelation(left, right) !== 'disjoint';
+}
+function opaque(value) {
+    return `sha256:${crypto.createHash('sha256').update(String(value)).digest('hex')}`;
+}
+/**
+ * Build the canonical descriptor for one requested resource.
+ * Input: {kind?, path?, port?, value?}. Unknown kinds are rejected rather than guessed.
+ */
+export function describeResource(input) {
+    if (input === null || typeof input !== 'object' || Array.isArray(input))
+        throw new Error('Resource must be an object');
+    const kind = input.kind ?? 'path';
+    if (!RESOURCE_KINDS.includes(kind))
+        throw new Error(`Unsupported resource kind: ${kind}`);
+    if (OPAQUE_KINDS.has(kind)) {
+        if (kind === 'port') {
+            if (typeof input.port !== 'number' ||
+                !Number.isSafeInteger(input.port) ||
+                input.port <= 0 ||
+                input.port > 65535)
+                throw new Error('Port must be an integer between 1 and 65535');
+            return {
+                kind,
+                scope: 'opaque',
+                key: `port:${input.port}`,
+                port: input.port,
+                label: input.label ?? `port ${input.port}`,
+            };
+        }
+        const value = input.value;
+        if (typeof value !== 'string' || value.trim().length === 0)
+            throw new Error('Opaque resources require a non-empty value');
+        return {
+            kind,
+            scope: 'opaque',
+            key: `${kind}:${value}`,
+            label: input.label ?? `${kind} ${value}`,
+        };
+    }
+    if (typeof input.path !== 'string')
+        throw new Error('Resource path must be a non-empty string');
+    const resolved = canonicalizeTarget(input.path);
+    // A not-yet-existing target is treated conservatively as a tree: claiming it also
+    // reserves anything created underneath it.
+    const scope = input.scope === 'file' ? 'file' : 'tree';
+    return {
+        kind,
+        scope,
+        key: `${kind}:${resolved.path}`,
+        path: resolved.path,
+        existing: resolved.existing,
+        label: input.label ?? `${kind} ${resolved.path}`,
+    };
+}
+/**
+ * Overlap between two claims. Path-like kinds compare on canonical paths; opaque kinds
+ * (ports, processes) only on exact keys. `port:` and `path:` never overlap.
+ */
+export function claimsOverlap(left, right) {
+    const leftOpaque = OPAQUE_KINDS.has(left.kind);
+    const rightOpaque = OPAQUE_KINDS.has(right.kind);
+    if (leftOpaque || rightOpaque)
+        return leftOpaque && rightOpaque && left.key === right.key;
+    if (!PATH_KINDS.has(left.kind) || !PATH_KINDS.has(right.kind))
+        return left.key === right.key;
+    if (typeof left.path !== 'string' || typeof right.path !== 'string')
+        throw new Error('Path resource requires a canonical path');
+    return pathsOverlap(left.path, right.path);
+}
+export function opaqueKey(prefix, value) {
+    return `${prefix}:${opaque(value)}`;
+}

package/dist/collab/contracts.d.ts

@@ -0,0 +1,73 @@
+import type { Identity, ResourceInput } from './types.js';
+export interface SkillRequirement {
+    id: string;
+    bundle_digest: string;
+}
+export interface Requirements {
+    skills: SkillRequirement[];
+    tools: string[];
+}
+export interface Assignment {
+    schema: string;
+    task_id: string;
+    assignment_id: string;
+    objective: string;
+    attempt: number;
+    roles: string[];
+    acceptance: string[];
+    coordinator: Pick<Identity, 'agent_id' | 'session_id'> & {
+        owner_epoch: number;
+        harness?: string | null;
+    };
+    assignee: Identity & {
+        harness: string;
+        cwd: string;
+        surface: string;
+        configuration_id: string;
+    };
+    inputs: {
+        ref: string;
+        digest: string;
+    }[];
+    resources: (ResourceInput & {
+        path: string;
+        access: string;
+        resource_epoch?: number;
+    })[];
+    runner: {
+        name: string;
+        mode: string;
+        profile?: string;
+        omitted_capabilities: string[];
+    };
+    required: Requirements;
+    preferred: Requirements;
+    [key: string]: unknown;
+}
+export interface Capability {
+    id: string;
+    state: string;
+    evidence_ref?: string;
+    path?: string;
+    bundle_digest?: string;
+}
+export interface CapabilityCard {
+    schema: string;
+    agent_id: string;
+    session_id: string;
+    harness: string;
+    surface: string;
+    configuration_id: string;
+    cwd: string;
+    observed_at: string;
+    evidence_level: string;
+    evidence_records?: {
+        ref: string;
+        digest: string;
+    }[];
+    skills: Capability[];
+    tools: Capability[];
+    [key: string]: unknown;
+}
+export declare function isAssignment(value: unknown): value is Assignment;
+export declare function isCard(value: unknown): value is CapabilityCard;

package/dist/collab/contracts.js

@@ -0,0 +1,76 @@
+import { object } from './validation.js';
+const string = (value) => typeof value === 'string';
+const strings = (value) => Array.isArray(value) && value.every(string);
+const number = (value) => typeof value === 'number' && Number.isSafeInteger(value);
+function requirements(value) {
+    return (object(value) &&
+        strings(value['tools']) &&
+        Array.isArray(value['skills']) &&
+        value['skills'].every((item) => object(item) && string(item['id']) && string(item['bundle_digest'])));
+}
+const refs = (value) => Array.isArray(value) &&
+    value.every((item) => object(item) && string(item['ref']) && string(item['digest']));
+export function isAssignment(value) {
+    if (!object(value) ||
+        !['schema', 'task_id', 'assignment_id', 'objective'].every((key) => string(value[key])))
+        return false;
+    const coordinator = value['coordinator'];
+    const assignee = value['assignee'];
+    const runner = value['runner'];
+    return (number(value['attempt']) &&
+        strings(value['roles']) &&
+        strings(value['acceptance']) &&
+        object(coordinator) &&
+        ['agent_id', 'session_id'].every((key) => string(coordinator[key])) &&
+        number(coordinator['owner_epoch']) &&
+        object(assignee) &&
+        [
+            'agent_id',
+            'session_id',
+            'harness',
+            'cwd',
+            'surface',
+            'configuration_id',
+        ].every((key) => string(assignee[key])) &&
+        refs(value['inputs']) &&
+        Array.isArray(value['resources']) &&
+        value['resources'].every((item) => object(item) &&
+            string(item['path']) &&
+            string(item['access']) &&
+            (item['kind'] === undefined || string(item['kind'])) &&
+            (item['port'] === undefined || number(item['port'])) &&
+            (item['resource_epoch'] === undefined ||
+                number(item['resource_epoch']))) &&
+        object(runner) &&
+        string(runner['name']) &&
+        string(runner['mode']) &&
+        strings(runner['omitted_capabilities']) &&
+        (runner['profile'] === undefined || string(runner['profile'])) &&
+        requirements(value['required']) &&
+        requirements(value['preferred']));
+}
+export function isCard(value) {
+    if (!object(value) ||
+        ![
+            'schema',
+            'agent_id',
+            'session_id',
+            'harness',
+            'surface',
+            'configuration_id',
+            'cwd',
+            'observed_at',
+            'evidence_level',
+        ].every((key) => string(value[key])))
+        return false;
+    return ((value['evidence_records'] === undefined ||
+        refs(value['evidence_records'])) &&
+        ['skills', 'tools'].every((kind) => {
+            const entries = value[kind];
+            return (Array.isArray(entries) &&
+                entries.every((item) => object(item) &&
+                    string(item['id']) &&
+                    string(item['state']) &&
+                    ['evidence_ref', 'path', 'bundle_digest'].every((key) => item[key] === undefined || string(item[key]))));
+        }));
+}

package/dist/collab/envelope.d.ts

@@ -0,0 +1,52 @@
+import type { Message, MessageInput } from './types.js';
+export declare const MESSAGE_SCHEMA = "harness-collab/message/1";
+export declare const MESSAGE_TYPES: readonly string[];
+export declare const REPORT_STATUSES: readonly string[];
+export declare const BLOCK_KINDS: readonly string[];
+export declare function validateEnvelope(message: unknown): Message;
+/** Stable JSON with sorted object keys, used for content-identity digests. */
+export declare function canonicalJson(value: unknown): string;
+/**
+ * Content identity of a message: everything that decides what the message means.
+ * `created_at` and `content_digest` are excluded so an honest resend is still the
+ * same message.
+ */
+export declare function contentDigest(message: Message): string;
+export declare function buildMessage(input: MessageInput, { clock }?: {
+    clock?: number | undefined;
+}): Message;
+export declare function messageFile(taskRoot: string, messageId: string): string;
+export declare function readRegisteredMessage(taskRoot: string, messageId: string): Message | null;
+/**
+ * Register a message exactly once. Returns:
+ *   registered            first registration; the caller may now apply it
+ *   duplicate             same id and same content; no new side effect
+ *   content_conflict      same id, different content; rejected
+ */
+export declare function registerMessage(taskRoot: string, message: Message, { clock }?: {
+    clock?: number | undefined;
+}): {
+    status: string;
+    message_id: string;
+    stored_digest: string;
+    actual_digest: string;
+    content_digest?: never;
+    file?: never;
+} | {
+    status: string;
+    message_id: string;
+    content_digest: string;
+    file: string;
+    stored_digest?: never;
+    actual_digest?: never;
+} | {
+    content_digest?: never;
+    status: string;
+    message_id: string;
+    stored_digest: string | null;
+    actual_digest: string;
+    file: string;
+};
+export declare function listRegisteredMessages(taskRoot: string): string[];
+export declare function sha256File(file: string): string;
+export declare function uniqueNonce(): string;

package/dist/collab/envelope.js

@@ -0,0 +1,241 @@
+import { errorCode, parseJson, object, text, isMessage } from './validation.js';
+import fs from 'node:fs';
+import path from 'node:path';
+import { createNonce, digestText, messagesDir, nowIso } from './store.js';
+// Message envelopes and their idempotency rules.
+//
+// Registration is an exclusive create of `messages/<message_id>.json`, which is atomic,
+// so two senders racing with the same id cannot both create it. Applying a registered
+// message to the record is a separate transaction: a crash between the two steps leaves
+// a `message_registered_not_applied` finding instead of a silent half-effect. The two
+// steps are never presented as one cross-system transaction.
+export const MESSAGE_SCHEMA = 'harness-collab/message/1';
+export const MESSAGE_TYPES = Object.freeze([
+    'ASSIGN',
+    'ACK',
+    'ASK',
+    'ANSWER',
+    'REPORT',
+    'STATUS_QUERY',
+    'STATUS',
+    'HANDOFF',
+    'BLOCK',
+    'CANCEL',
+    'CANCELLED',
+]);
+export const REPORT_STATUSES = Object.freeze([
+    'running',
+    'completed',
+    'needs_input',
+    'failed',
+    'cancelled',
+    'unknown',
+]);
+export const BLOCK_KINDS = Object.freeze(['clarification', 'approval']);
+const REQUIRE_IDENTITY = ['agent_id', 'session_id', 'harness'];
+const TYPE_RULES = {
+    ASSIGN: {
+        to: true,
+        subtask: true,
+        attempt: true,
+        body: ['assignment_digest'],
+    },
+    ACK: { to: true, reply_to: true },
+    ASK: { to: true },
+    ANSWER: { to: true, reply_to: true },
+    REPORT: { to: true, subtask: true, attempt: true, body: ['status'] },
+    STATUS_QUERY: { to: true },
+    STATUS: { to: true, reply_to: true, body: ['status'] },
+    HANDOFF: { to: true, subtask: true, body: ['handoff_id', 'phase'] },
+    BLOCK: { to: true, body: ['kind'] },
+    CANCEL: { to: true, subtask: true, attempt: true },
+    CANCELLED: { to: true, reply_to: true, subtask: true, attempt: true },
+};
+function assert(condition, field) {
+    if (!condition)
+        throw new Error(`Invalid message field: ${field}`);
+}
+function identity(value, field) {
+    assert(object(value), field);
+    for (const key of REQUIRE_IDENTITY)
+        assert(text(value[key]), `${field}.${key}`);
+}
+export function validateEnvelope(message) {
+    assert(isMessage(message), 'message');
+    assert(message.schema === MESSAGE_SCHEMA, 'message.schema');
+    assert(text(message.message_id) && message.message_id.length <= 128, 'message.message_id');
+    assert(MESSAGE_TYPES.includes(message.type), 'message.type');
+    assert(text(message.task_id), 'message.task_id');
+    identity(message.from, 'message.from');
+    const rule = TYPE_RULES[message.type];
+    assert(rule, 'message.type');
+    if (rule.to)
+        identity(message.to, 'message.to');
+    if (rule.reply_to)
+        assert(text(message.reply_to), 'message.reply_to');
+    if (rule.subtask)
+        assert(text(message.subtask_id), 'message.subtask_id');
+    if (rule.attempt)
+        assert(Number.isSafeInteger(message.attempt) && (message.attempt ?? 0) > 0, 'message.attempt');
+    if (message.owner_epoch !== undefined && message.owner_epoch !== null) {
+        assert(Number.isSafeInteger(message.owner_epoch) && message.owner_epoch > 0, 'message.owner_epoch');
+    }
+    if (message.body !== undefined)
+        assert(object(message.body), 'message.body');
+    for (const key of rule.body ?? [])
+        assert(message.body !== undefined && message.body[key] !== undefined, `message.body.${key}`);
+    if (message.body?.status !== undefined)
+        assert(REPORT_STATUSES.includes(message.body.status), 'message.body.status');
+    // `body.kind` is scoped per message type; the same field name means different things.
+    if (message.type === 'BLOCK' && message.body?.kind !== undefined)
+        assert(BLOCK_KINDS.includes(message.body.kind), 'message.body.kind');
+    if (message.type === 'HANDOFF' && message.body?.kind !== undefined)
+        assert(['writer', 'coordinator'].includes(message.body.kind), 'message.body.kind');
+    if (message.body?.approval !== undefined) {
+        assert(object(message.body.approval) &&
+            text(message.body.approval.approved_by) &&
+            text(message.body.approval.reason), 'message.body.approval');
+    }
+    // Unknown extension fields are tolerated on purpose; unknown semantics are not inferred.
+    return message;
+}
+/** Stable JSON with sorted object keys, used for content-identity digests. */
+export function canonicalJson(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value ?? null);
+    if (Array.isArray(value))
+        return `[${value.map((item) => canonicalJson(item)).join(',')}]`;
+    if (!object(value))
+        throw new Error('Canonical JSON requires an object');
+    const keys = Object.keys(value).sort();
+    return `{${keys.map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`).join(',')}}`;
+}
+/**
+ * Content identity of a message: everything that decides what the message means.
+ * `created_at` and `content_digest` are excluded so an honest resend is still the
+ * same message.
+ */
+export function contentDigest(message) {
+    const content = {
+        type: message.type,
+        task_id: message.task_id,
+        subtask_id: message.subtask_id ?? null,
+        attempt: message.attempt ?? null,
+        from: message.from,
+        to: message.to ?? null,
+        reply_to: message.reply_to ?? null,
+        owner_epoch: message.owner_epoch ?? null,
+        body: message.body ?? null,
+    };
+    return digestText(canonicalJson(content));
+}
+export function buildMessage(input, { clock = Date.now() } = {}) {
+    const message = {
+        schema: MESSAGE_SCHEMA,
+        message_id: input.message_id ?? `msg-${createNonce()}`,
+        type: input.type,
+        task_id: input.task_id,
+        from: input.from,
+        to: input.to,
+        reply_to: input.reply_to ?? null,
+        subtask_id: input.subtask_id ?? null,
+        attempt: input.attempt ?? null,
+        owner_epoch: input.owner_epoch ?? null,
+        created_at: input.created_at ?? nowIso(clock),
+        content_digest: null,
+        body: input.body ?? {},
+    };
+    validateEnvelope(message);
+    message.content_digest = contentDigest(message);
+    return message;
+}
+export function messageFile(taskRoot, messageId) {
+    if (/[\\/\0]/.test(messageId))
+        throw new Error('Invalid message field: message.message_id');
+    return path.join(messagesDir(taskRoot), `${messageId}.json`);
+}
+export function readRegisteredMessage(taskRoot, messageId) {
+    const file = messageFile(taskRoot, messageId);
+    try {
+        return validateEnvelope(parseJson(fs.readFileSync(file, 'utf8')));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Register a message exactly once. Returns:
+ *   registered            first registration; the caller may now apply it
+ *   duplicate             same id and same content; no new side effect
+ *   content_conflict      same id, different content; rejected
+ */
+export function registerMessage(taskRoot, message, { clock = Date.now() } = {}) {
+    validateEnvelope(message);
+    const digest = contentDigest(message);
+    if (message.content_digest && message.content_digest !== digest) {
+        return {
+            status: 'content_conflict',
+            message_id: message.message_id,
+            stored_digest: message.content_digest,
+            actual_digest: digest,
+        };
+    }
+    fs.mkdirSync(messagesDir(taskRoot), { recursive: true, mode: 0o700 });
+    const stored = {
+        ...message,
+        content_digest: digest,
+        created_at: message.created_at ?? nowIso(clock),
+    };
+    const file = messageFile(taskRoot, message.message_id);
+    try {
+        fs.writeFileSync(file, `${JSON.stringify(stored, null, 2)}\n`, {
+            flag: 'wx',
+            mode: 0o600,
+        });
+        return {
+            status: 'registered',
+            message_id: message.message_id,
+            content_digest: digest,
+            file,
+        };
+    }
+    catch (error) {
+        if (errorCode(error) !== 'EEXIST')
+            throw error;
+        const existing = readRegisteredMessage(taskRoot, message.message_id);
+        const existingDigest = existing ? contentDigest(existing) : null;
+        if (existing && existingDigest === digest) {
+            return {
+                status: 'duplicate',
+                message_id: message.message_id,
+                content_digest: digest,
+                file,
+            };
+        }
+        return {
+            status: 'content_conflict',
+            message_id: message.message_id,
+            stored_digest: existingDigest,
+            actual_digest: digest,
+            file,
+        };
+    }
+}
+export function listRegisteredMessages(taskRoot) {
+    try {
+        return fs
+            .readdirSync(messagesDir(taskRoot))
+            .filter((name) => name.endsWith('.json'))
+            .map((name) => name.slice(0, -'.json'.length))
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+export function sha256File(file) {
+    return digestText(fs.readFileSync(file));
+}
+export function uniqueNonce() {
+    return createNonce();
+}

package/dist/collab/fingerprint.d.ts

@@ -0,0 +1,7 @@
+/** Fingerprint one explicitly selected skill, including its supporting files. */
+export declare function fingerprintSkill(input: string): {
+    path: string;
+    entry_digest: string;
+    bundle_digest: string;
+    file_count: number;
+};

package/dist/collab/fingerprint.js

@@ -0,0 +1,58 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+const sha256 = (value) => `sha256:${crypto.createHash('sha256').update(value).digest('hex')}`;
+/** Fingerprint one explicitly selected skill, including its supporting files. */
+export function fingerprintSkill(input) {
+    if (!path.isAbsolute(input))
+        throw new Error('Skill path must be absolute');
+    const resolved = fs.realpathSync(input);
+    const root = fs.statSync(resolved).isDirectory()
+        ? resolved
+        : path.dirname(resolved);
+    if (!fs.statSync(resolved).isDirectory() &&
+        path.basename(resolved) !== 'SKILL.md') {
+        throw new Error('Select a skill directory or SKILL.md');
+    }
+    const entry = path.join(root, 'SKILL.md');
+    const files = [];
+    let totalBytes = 0;
+    let directoryCount = 0;
+    function visit(directory) {
+        if (++directoryCount > 1000)
+            throw new Error('Skill exceeds the directory limit');
+        for (const name of fs.readdirSync(directory).sort()) {
+            const file = path.join(directory, name);
+            const stat = fs.lstatSync(file);
+            if (stat.isSymbolicLink())
+                throw new Error('Supporting symlinks require an explicitly packaged skill');
+            if (stat.isDirectory()) {
+                visit(file);
+            }
+            else if (stat.isFile()) {
+                totalBytes += stat.size;
+                if (files.length >= 1000 || totalBytes > 16 * 1024 * 1024) {
+                    throw new Error('Skill exceeds the fingerprint size limit');
+                }
+                files.push([
+                    path.relative(root, file).split(path.sep).join('/'),
+                    sha256(fs.readFileSync(file)),
+                ]);
+            }
+            else {
+                throw new Error('Skill contains an unsupported file type');
+            }
+        }
+    }
+    visit(root);
+    files.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    const entryRow = files.find(([name]) => name === 'SKILL.md');
+    if (!entryRow)
+        throw new Error('Skill entry is missing');
+    return {
+        path: entry,
+        entry_digest: entryRow[1],
+        bundle_digest: sha256(JSON.stringify(files)),
+        file_count: files.length,
+    };
+}