@adhdev/mesh-shared 1.0.60-rc.4 → 1.0.60-rc.41

package/src/outbound-message.ts

@@ -0,0 +1,320 @@
+/**
+ * outbound-message — the one send-side unit crossing every transport.
+ *
+ * Wiring-unification Phase D (docs/design/2026-09-23-wiring-unification.md §6,
+ * D1) / workstream D-web. Full type derivation in the scratchpad
+ * `phase-D-plan.md` §1.1-§1.2 (`OutboundMessage`/`SendPolicy`/`SubmitOutcome`/
+ * `SendRefusal`). `SendRefusal` is imported from here by Phase C1's
+ * `turn-evidence.ts` (`RECLAIMING_SEND_REFUSALS`) — this file owns the type,
+ * C1 owns which of its members reclaim a mesh dispatch attempt.
+ *
+ * Before this type, a chat send was represented by twelve different loose
+ * request shapes (`{message, sendNow?, interrupt?}`, `{message, input}`,
+ * mesh `agent_command` args, MCP tool args, ...) and parked messages had no
+ * identity at all — the driver queue was keyed by exact text, so send-now,
+ * cancel, interrupt and the web echo-retirement all recovered identity by
+ * string matching. `OutboundMessage.messageId` is minted once, at the
+ * ORIGIN, and is the identity every layer keys on afterwards: the wire
+ * field in the `send_chat` command payload, the driver's queue key (daemon
+ * side, Phase D-daemon), the web pending-store key (`pendingQueuedMessages.ts`)
+ * and the echo-retirement key (`conversation-message-snapshot.ts`).
+ *
+ * This file is dependency-free by construction (mesh-shared leaf rule):
+ * `InputEnvelopeWire`/`InputPartWire` are STRUCTURAL MIRRORS of daemon-core's
+ * `InputEnvelope`/`InputPart` (`oss/packages/daemon-core/src/providers/
+ * io-contracts.ts`), not re-exports — daemon-core assigns its richer type
+ * into this one, never the other way round, so this package's published
+ * `.d.ts` never references a package that depends on it.
+ */
+
+// ─── Input envelope (structural mirror of daemon-core's InputEnvelope) ─────
+
+export interface ContentAnnotationsWire {
+    audience?: ('user' | 'assistant')[]
+    priority?: number
+}
+
+export interface TextInputPartWire {
+    type: 'text'
+    text: string
+}
+
+export interface ImageInputPartWire {
+    type: 'image'
+    mimeType: string
+    uri?: string
+    data?: string
+    alt?: string
+}
+
+export interface AudioInputPartWire {
+    type: 'audio'
+    mimeType: string
+    uri?: string
+    data?: string
+    transcript?: string
+}
+
+export interface VideoInputPartWire {
+    type: 'video'
+    mimeType: string
+    uri?: string
+    data?: string
+    transcript?: string
+    posterUri?: string
+}
+
+export interface ResourceInputPartWire {
+    type: 'resource'
+    uri: string
+    mimeType?: string
+    name?: string
+    text?: string
+    data?: string
+}
+
+export interface ResourceLinkInputPartWire {
+    type: 'resource_link'
+    uri: string
+    name: string
+    title?: string
+    description?: string
+    mimeType?: string
+    size?: number
+    annotations?: ContentAnnotationsWire
+}
+
+export type InputPartWire =
+    | TextInputPartWire
+    | ImageInputPartWire
+    | AudioInputPartWire
+    | VideoInputPartWire
+    | ResourceLinkInputPartWire
+    | ResourceInputPartWire
+
+export interface InputEnvelopeWire {
+    parts: InputPartWire[]
+    textFallback: string
+    metadata?: {
+        source?: 'dashboard' | 'shortcut_api' | 'provider_script' | 'session_replay'
+        clientTimestamp?: number
+    }
+}
+
+// ─── OutboundMessage ────────────────────────────────────────────────────────
+
+/**
+ * Who minted this `OutboundMessage`. Determines default policy and refusal
+ * surface — 'mesh' origins get the mesh-specific `SendRefusal` reasons,
+ * interactive origins get the interactive ones.
+ *
+ * `'api'`/`'cli'` are carried per the design doc's D1 type even though no
+ * current call site produces them distinct from `'dashboard'`/`'mcp'`/
+ * `'mesh'` (flagged as an open question in phase-D-plan.md §7.3 risk 5) —
+ * kept here unchanged pending an owner decision; dropping a union member is
+ * a decision for whoever lands D-daemon/D2, not this workstream.
+ */
+export type OutboundMessageOrigin = 'dashboard' | 'mcp' | 'mesh' | 'api' | 'cli'
+
+/**
+ * How this message should be admitted when the session is not idle.
+ * Replaces the loose `sendNow`/`interrupt`/`force`/`forceSend` booleans (and
+ * mesh `delivery_mode`) with one closed union. `'queue'` is the default for
+ * every origin.
+ */
+export type SendPolicy =
+    | { mode: 'queue' }
+    | { mode: 'send_now' }
+    | { mode: 'interrupt' }
+
+/**
+ * Every reason `submit()` can refuse a message, closed so callers branch on it
+ * instead of matching free text.
+ *
+ * ★ This is THE `SendRefusal` (docs/design/2026-09-23-wiring-unification.md
+ * §6 D1) — Phase C1's `turn-evidence.ts` imports `SendRefusal`/
+ * `SEND_REFUSAL_REASONS` from this file (`RECLAIMING_SEND_REFUSALS`, the
+ * subset that means a mesh dispatch attempt must be reclaimed rather than
+ * retried) rather than declaring its own copy. Do not fork this vocabulary —
+ * a member renamed or removed here must be re-checked against
+ * `RECLAIMING_SEND_REFUSALS`'s three members (`session_exited`, `no_target`,
+ * `unsupported_input`), which `satisfies readonly SendRefusal[]` there keeps
+ * honest at compile time.
+ */
+export type SendRefusal =
+    | 'not_ready'
+    | 'send_in_flight'
+    | 'not_generating'
+    | 'not_supported'
+    | 'platform_unsupported'
+    | 'modal_parked'
+    | 'interrupt_not_implemented'
+    | 'interrupt_refused'
+    | 'idle_timeout'
+    | 'session_exited'
+    | 'unsupported_input'
+    | 'no_target'
+    | 'bootstrap_pending'
+    | 'duplicate_dispatch'
+    | 'internal_error'
+
+/**
+ * Which write path carried a delivered/queued message (Phase D2, additive
+ * detail — callers branch on `kind`; `route` only refines the report):
+ *
+ *   `pty`         — the ordinary composer write (or the driver FIFO for `queued`);
+ *   `agent_queue` — the POSIX split write the CLI's OWN input queue takes while
+ *                   a turn is generating (`send_now`). Written, not yet answered;
+ *   `interrupt`   — the turn in flight was stopped first, then this body was
+ *                   written (or re-parked) as a new turn;
+ *   `acp`         — handed to an ACP agent's `session/prompt`.
+ */
+export type SubmitRoute = 'pty' | 'agent_queue' | 'interrupt' | 'acp'
+
+/** The stop key pressed by an `interrupt` submit (logs / operator display). */
+export interface SubmitInterruptDetail {
+    keyName: string
+    /** 'declared' = spec-declared stop key whose busy→idle effect was never observed live. */
+    confidence: 'proven' | 'declared'
+}
+
+/**
+ * The one closed outcome shape every caller receives from `submit()`.
+ *
+ * The optional fields are additive DETAIL (Phase D2): `route`/`interrupt` say
+ * how a message was written, `message` is a human-readable refusal line and
+ * `restored` says whether a parked body that an out-of-band submit had claimed
+ * is back in the driver queue (`false` = nothing holds it any more). None of
+ * them changes what `kind` means.
+ */
+export type SubmitOutcome =
+    | { kind: 'delivered'; route?: SubmitRoute; interrupt?: SubmitInterruptDetail }
+    | { kind: 'queued'; position: number; route?: SubmitRoute; interrupt?: SubmitInterruptDetail }
+    | { kind: 'duplicate'; of: string /* messageId */ }
+    | { kind: 'refused'; reason: SendRefusal; message?: string; restored?: boolean }
+
+/**
+ * The one send-side unit crossing every transport. `messageId` is minted at
+ * the ORIGIN (never by the daemon) — this is what makes cross-transport
+ * dedupe and identity-based claim/cancel/send-now possible.
+ */
+export interface OutboundMessage {
+    messageId: string
+    sessionId: string
+    input: InputEnvelopeWire
+    origin: OutboundMessageOrigin
+    policy: SendPolicy
+    createdAt: number
+    /**
+     * Present only for a mesh-dispatched message; lets the turn ledger
+     * (Phase C) bind the send to the attempt without the sender needing to
+     * know what an "attempt" is. Optional and inert until C lands.
+     */
+    meshAttemptRef?: string
+}
+
+// ─── Identity ───────────────────────────────────────────────────────────────
+
+/**
+ * Mint a new `messageId`. `crypto.randomUUID` where available (browser and
+ * modern Node); a counter fallback otherwise, since the only requirement is
+ * uniqueness within one process/tab, not cryptographic strength.
+ */
+let outboundMessageIdCounter = 0
+export function mintMessageId(now: number = Date.now()): string {
+    try {
+        // `globalThis.crypto` is not in the ES2022 lib (mesh-shared is DOM-free), so read it structurally.
+        const cryptoRef = (typeof globalThis !== 'undefined'
+            ? (globalThis as { crypto?: { randomUUID?: () => string } }).crypto
+            : undefined)
+        if (typeof cryptoRef?.randomUUID === 'function') return `msg_${cryptoRef.randomUUID()}`
+    } catch {
+        /* fall through to the counter fallback */
+    }
+    outboundMessageIdCounter += 1
+    return `msg_${now}_${outboundMessageIdCounter}`
+}
+
+/** `messageId`s minted by this module always carry this prefix; used by the guard below. */
+const MESSAGE_ID_PREFIX = 'msg_'
+
+export function isMessageId(value: unknown): value is string {
+    return typeof value === 'string' && value.length > MESSAGE_ID_PREFIX.length && value.startsWith(MESSAGE_ID_PREFIX)
+}
+
+// ─── Guards ─────────────────────────────────────────────────────────────────
+
+export const OUTBOUND_MESSAGE_ORIGINS = ['dashboard', 'mcp', 'mesh', 'api', 'cli'] as const satisfies readonly OutboundMessageOrigin[]
+
+export function isOutboundMessageOrigin(value: unknown): value is OutboundMessageOrigin {
+    return typeof value === 'string' && (OUTBOUND_MESSAGE_ORIGINS as readonly string[]).includes(value)
+}
+
+export const SEND_POLICY_MODES = ['queue', 'send_now', 'interrupt'] as const satisfies readonly SendPolicy['mode'][]
+
+export function isSendPolicyMode(value: unknown): value is SendPolicy['mode'] {
+    return typeof value === 'string' && (SEND_POLICY_MODES as readonly string[]).includes(value)
+}
+
+export function isSendPolicy(value: unknown): value is SendPolicy {
+    return !!value && typeof value === 'object' && isSendPolicyMode((value as { mode?: unknown }).mode)
+}
+
+export const SEND_REFUSAL_REASONS = [
+    'not_ready',
+    'send_in_flight',
+    'not_generating',
+    'not_supported',
+    'platform_unsupported',
+    'modal_parked',
+    'interrupt_not_implemented',
+    'interrupt_refused',
+    'idle_timeout',
+    'session_exited',
+    'unsupported_input',
+    'no_target',
+    'bootstrap_pending',
+    'duplicate_dispatch',
+    'internal_error',
+] as const satisfies readonly SendRefusal[]
+
+export function isSendRefusal(value: unknown): value is SendRefusal {
+    return typeof value === 'string' && (SEND_REFUSAL_REASONS as readonly string[]).includes(value)
+}
+
+const SUBMIT_OUTCOME_KINDS = ['delivered', 'queued', 'duplicate', 'refused'] as const
+
+export function isSubmitOutcome(value: unknown): value is SubmitOutcome {
+    if (!value || typeof value !== 'object') return false
+    const kind = (value as { kind?: unknown }).kind
+    if (typeof kind !== 'string' || !(SUBMIT_OUTCOME_KINDS as readonly string[]).includes(kind)) return false
+    if (kind === 'queued') return typeof (value as { position?: unknown }).position === 'number'
+    if (kind === 'duplicate') return typeof (value as { of?: unknown }).of === 'string'
+    if (kind === 'refused') return isSendRefusal((value as { reason?: unknown }).reason)
+    return true
+}
+
+function isInputPartWire(value: unknown): value is InputPartWire {
+    if (!value || typeof value !== 'object') return false
+    const type = (value as { type?: unknown }).type
+    return type === 'text' || type === 'image' || type === 'audio' || type === 'video' || type === 'resource' || type === 'resource_link'
+}
+
+export function isInputEnvelopeWire(value: unknown): value is InputEnvelopeWire {
+    if (!value || typeof value !== 'object') return false
+    const parts = (value as { parts?: unknown }).parts
+    const textFallback = (value as { textFallback?: unknown }).textFallback
+    return Array.isArray(parts) && parts.every(isInputPartWire) && typeof textFallback === 'string'
+}
+
+/** Minimal structural check for the wire boundary — not a full decoder (mesh-shared stays a pure leaf; semantic validation stays with the handler that owns it). */
+export function isOutboundMessage(value: unknown): value is OutboundMessage {
+    if (!value || typeof value !== 'object') return false
+    const candidate = value as Partial<OutboundMessage>
+    return isMessageId(candidate.messageId)
+        && typeof candidate.sessionId === 'string' && candidate.sessionId.length > 0
+        && isInputEnvelopeWire(candidate.input)
+        && isOutboundMessageOrigin(candidate.origin)
+        && isSendPolicy(candidate.policy)
+        && typeof candidate.createdAt === 'number'
+}

package/src/path-ownership.ts

@@ -0,0 +1,271 @@
+/**
+ * path-ownership — declared file-ownership sets for `code_change` mesh tasks
+ * (wiring-unification Phase H1, `docs/design/2026-09-23-wiring-unification.md`
+ * §7c).
+ *
+ * Today two `code_change` tasks on two different nodes (two worktrees of the
+ * same branch, or main + a worktree) can silently touch the same file with
+ * zero warning — the only existing isolation is node-level ("one active write
+ * task per node"), never path-level. This module is the pure, dependency-free
+ * core of the fix: normalizing a caller-declared `owned_paths` list, and
+ * comparing declared sets for overlap. It has NO opinion on enforcement policy
+ * (refuse vs warn, which axis a caller compares against) — that is the mesh
+ * runtime's job (`claimNextTask` / `claimNextQueueTask` in daemon-core); this
+ * module only answers "do these two declarations conflict" and "did the
+ * touched-files report stay inside the declaration".
+ *
+ * SCOPE DECISION (glob support): minimal, deliberately. A declaration entry is
+ * either an exact repo-relative path (`src/foo.ts`) or a directory prefix
+ * spelled with a trailing `/**` (`src/mesh/**`) meaning "this path and
+ * everything under it". No `*`/`?` mid-segment wildcards, no `!` negation, no
+ * brace expansion. Two `code_change` tasks racing on overlapping files is a
+ * coordination bug to catch, not a general glob engine to build — a full
+ * minimatch-style matcher would need its own test suite and still leave the
+ * same ambiguity (does `src/*.ts` "contain" `src/foo.ts`?) the design doc's
+ * risk list calls out. `src/` (no `**`) is treated as an exact single-path
+ * entry, i.e. it owns a literal file/dir node named `src`, NOT everything
+ * under it — callers who want subtree ownership must write `src/**`.
+ *
+ * Rejected inputs (absolute paths, `..` segments, backslash-only entries that
+ * still resolve outside the repo after normalization) are dropped rather than
+ * silently coerced — `normalizeOwnedPaths` reports what it dropped so the
+ * caller (enqueue-time validation) can decide whether to warn or refuse.
+ */
+
+/** One normalized ownership entry: a repo-relative path, optionally a `**` subtree prefix. */
+export interface OwnedPathEntry {
+    /** Repo-relative path with forward slashes, no leading `./`, no trailing slash. */
+    readonly path: string
+    /** True when this entry was declared as `<path>/**` (owns the whole subtree). */
+    readonly subtree: boolean
+}
+
+/** A caller's normalized ownership declaration. */
+export interface OwnedPathsDeclaration {
+    readonly paths: readonly OwnedPathEntry[]
+}
+
+export interface NormalizeOwnedPathsResult {
+    readonly declaration: OwnedPathsDeclaration
+    /** Raw input entries that were dropped, with why — surfaced to the caller, never silently coerced. */
+    readonly rejected: ReadonlyArray<{ input: string; reason: string }>
+}
+
+/** Cap mirrors `depends_on`'s implicit list-size discipline (design doc H1 proposal). */
+export const MAX_OWNED_PATHS = 64
+
+function toPosix(raw: string): string {
+    return raw.replace(/\\/g, '/')
+}
+
+/**
+ * Normalize one raw entry. Returns `null` (with a reason pushed to `rejected`)
+ * for anything absolute, escaping the repo via `..`, or empty after trimming.
+ */
+function normalizeOne(raw: unknown, rejected: Array<{ input: string; reason: string }>): OwnedPathEntry | null {
+    if (typeof raw !== 'string') {
+        rejected.push({ input: String(raw), reason: 'not_a_string' })
+        return null
+    }
+    const trimmed = raw.trim()
+    if (!trimmed) {
+        rejected.push({ input: raw, reason: 'empty' })
+        return null
+    }
+    let posix = toPosix(trimmed)
+
+    // Absolute paths (POSIX `/…`, Windows drive letter `C:\…` or `C:/…`, or a
+    // stray leading `~`) are refused outright — ownership is repo-relative by
+    // construction, and accepting an absolute path would let a declaration
+    // silently escape the workspace it is meant to scope.
+    if (posix.startsWith('/') || /^[a-zA-Z]:\//.test(posix) || posix.startsWith('~')) {
+        rejected.push({ input: raw, reason: 'absolute_path' })
+        return null
+    }
+
+    // Strip a leading './'.
+    posix = posix.replace(/^\.\/+/, '')
+
+    // Reject any '..' segment anywhere — no escaping the repo root.
+    const segments = posix.split('/').filter(Boolean)
+    if (segments.some(seg => seg === '..')) {
+        rejected.push({ input: raw, reason: 'parent_traversal' })
+        return null
+    }
+    if (segments.length === 0) {
+        rejected.push({ input: raw, reason: 'empty' })
+        return null
+    }
+
+    // Minimal glob support: a trailing '**' segment (from '<path>/**') marks a
+    // subtree declaration. Any OTHER '*'/'?' anywhere is rejected — this module
+    // does not implement general glob matching (see module doc).
+    let subtree = false
+    if (segments[segments.length - 1] === '**') {
+        subtree = true
+        segments.pop()
+        if (segments.length === 0) {
+            // '**' alone (or './**') claims the entire repo — allowed, but the
+            // caller (enqueue-time validation) is expected to lint/warn on it
+            // per the design doc's deadlock risk; this module only normalizes.
+        }
+    }
+    if (segments.some(seg => seg.includes('*') || seg.includes('?'))) {
+        rejected.push({ input: raw, reason: 'unsupported_glob' })
+        return null
+    }
+
+    return { path: segments.join('/'), subtree }
+}
+
+/**
+ * Normalize a caller-supplied `owned_paths` array. Never throws — invalid
+ * entries are dropped and reported in `rejected`; duplicates (after
+ * normalization) collapse to one entry (subtree wins if either declaration
+ * form is present for the same path). Entries beyond `MAX_OWNED_PATHS` (after
+ * dedup) are dropped with reason `over_cap`, preserving declaration order.
+ */
+export function normalizeOwnedPaths(input: unknown): NormalizeOwnedPathsResult {
+    const rejected: Array<{ input: string; reason: string }> = []
+    if (input === undefined || input === null) {
+        return { declaration: { paths: [] }, rejected }
+    }
+    if (!Array.isArray(input)) {
+        return { declaration: { paths: [] }, rejected: [{ input: String(input), reason: 'not_an_array' }] }
+    }
+
+    const byPath = new Map<string, OwnedPathEntry>()
+    for (const raw of input) {
+        const entry = normalizeOne(raw, rejected)
+        if (!entry) continue
+        const existing = byPath.get(entry.path)
+        if (!existing) {
+            byPath.set(entry.path, entry)
+        } else if (entry.subtree && !existing.subtree) {
+            byPath.set(entry.path, entry)
+        }
+        // else: duplicate, existing entry already at least as broad — keep it.
+    }
+
+    const all = [...byPath.values()]
+    const kept = all.slice(0, MAX_OWNED_PATHS)
+    for (const dropped of all.slice(MAX_OWNED_PATHS)) {
+        rejected.push({ input: dropped.path, reason: 'over_cap' })
+    }
+
+    return { declaration: { paths: kept }, rejected }
+}
+
+/** True when `path` is exactly `base`, or (when `base` is a subtree entry) nested under it. */
+function entryContains(base: OwnedPathEntry, path: string): boolean {
+    if (path === base.path) return true
+    if (base.subtree && (path === base.path || path.startsWith(`${base.path}/`))) return true
+    return false
+}
+
+/** True when two normalized entries' claimed sets intersect (exact match, or one contains the other's directory). */
+function entriesOverlap(a: OwnedPathEntry, b: OwnedPathEntry): boolean {
+    if (a.path === b.path) return true
+    if (a.subtree && (b.path === a.path || b.path.startsWith(`${a.path}/`))) return true
+    if (b.subtree && (a.path === b.path || a.path.startsWith(`${b.path}/`))) return true
+    return false
+}
+
+/** True when two declarations claim any overlapping path. Pure set comparison — no policy (refuse vs warn) here. */
+export function pathsOverlap(a: OwnedPathsDeclaration, b: OwnedPathsDeclaration): boolean {
+    if (a.paths.length === 0 || b.paths.length === 0) return false
+    for (const pa of a.paths) {
+        for (const pb of b.paths) {
+            if (entriesOverlap(pa, pb)) return true
+        }
+    }
+    return false
+}
+
+export interface InFlightOwnership {
+    readonly taskId: string
+    readonly paths: OwnedPathsDeclaration
+}
+
+export interface OwnershipConflict {
+    readonly taskId: string
+    /** The specific overlapping paths, for a readable refusal message. */
+    readonly overlappingPaths: readonly string[]
+}
+
+/**
+ * Compare a candidate declaration against every other in-flight task's
+ * declaration and return every conflict found (not just the first), each
+ * naming the owning task id and the specific overlapping path(s) — so a
+ * refusal message can say exactly what collided, not just that it did.
+ *
+ * Backward compatibility (design doc risk #4): an EMPTY candidate declaration
+ * never conflicts (opt-in only — absent `owned_paths` performs no overlap
+ * check for that task), and an in-flight entry with an empty declaration is
+ * never reported as a conflict source either.
+ */
+export function findOwnershipConflicts(
+    candidate: OwnedPathsDeclaration,
+    inFlight: readonly InFlightOwnership[],
+): OwnershipConflict[] {
+    if (candidate.paths.length === 0) return []
+    const conflicts: OwnershipConflict[] = []
+    for (const other of inFlight) {
+        if (other.paths.paths.length === 0) continue
+        const overlappingPaths: string[] = []
+        for (const pa of candidate.paths) {
+            for (const pb of other.paths.paths) {
+                if (entriesOverlap(pa, pb)) {
+                    const narrower = pa.path.length >= pb.path.length ? pa.path : pb.path
+                    if (!overlappingPaths.includes(narrower)) overlappingPaths.push(narrower)
+                }
+            }
+        }
+        if (overlappingPaths.length > 0) {
+            conflicts.push({ taskId: other.taskId, overlappingPaths })
+        }
+    }
+    return conflicts
+}
+
+export interface TouchedFilesOutsideOwnershipResult {
+    /** Touched files not covered by any declared owned-path entry. */
+    readonly undeclaredTouched: readonly string[]
+    /** Declared entries that no touched file matched (informational only — under-reporting is not flagged as a mismatch by policy, just visible here). */
+    readonly unusedDeclarations: readonly string[]
+}
+
+/**
+ * Compare a worker's `report_completion.touched_files` against its task's
+ * declared `owned_paths`. Pure comparison only — per the design doc, a
+ * mismatch is "surfaced as evidence, not silently accepted"; this function
+ * does not decide whether that is an error. Each `touched` entry is
+ * normalized with the same rules as a declaration (invalid entries — e.g. an
+ * absolute path a worker reported by mistake — are treated as undeclared
+ * rather than silently dropped, since they cannot match anything).
+ */
+export function touchedFilesOutsideOwnership(
+    touched: readonly string[],
+    owned: OwnedPathsDeclaration,
+): TouchedFilesOutsideOwnershipResult {
+    const undeclaredTouched: string[] = []
+    const usedDeclarations = new Set<string>()
+
+    for (const raw of touched ?? []) {
+        const rejectedSink: Array<{ input: string; reason: string }> = []
+        const entry = normalizeOne(raw, rejectedSink)
+        if (!entry) {
+            undeclaredTouched.push(raw)
+            continue
+        }
+        const matches = owned.paths.filter(base => entryContains(base, entry.path))
+        if (matches.length === 0) {
+            undeclaredTouched.push(entry.path)
+        } else {
+            for (const m of matches) usedDeclarations.add(m.path)
+        }
+    }
+
+    const unusedDeclarations = owned.paths.map(p => p.path).filter(p => !usedDeclarations.has(p))
+    return { undeclaredTouched, unusedDeclarations }
+}