@dsh-electron/dsh-plugin-multi-root-workspace 0.1.5 → 0.1.7

package/lib/types/profile-isolation.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Profile pnpm import isolation — the host-side maintenance behind
+ * `/workspace-folders isolate-profiles` (branch review Phase C2, finding R4).
+ *
+ * Why it exists: a Windows deny ACE applies to the file OBJECT, not to one
+ * hardlink name. The pnpm profile defaults upstream writes (`initProfile` in
+ * dsh-app-boot) never set `packageImportMethod`, so `dsh plugin add` imports
+ * the store into `<home>/profiles/<name>/node_modules` BY HARDLINK. Denying
+ * `$DSH_HOME` then rewrites security descriptors shared with every other name
+ * of the same objects — including the global pnpm store and other projects
+ * linking it. The C1 preflight therefore refuses such a home before any ACL
+ * write; this module is the remediation it points at: it detects the confirmed
+ * profiles, writes `packageImportMethod: copy` conservatively, and scans the
+ * whole home for the multi-link files that still need a reinstall.
+ *
+ * Boundaries of the subset it touches:
+ * - profile identification is conservative — only a directory under
+ *   `profiles/` whose `package.json` parses to an object carrying
+ *   `dsh.profile` as an object counts; everything else is enumerated but
+ *   never written;
+ * - the YAML handling is a strict SUBSET scanner, not a parser substitute —
+ *   the runtime cannot depend on a YAML package, so anything ambiguous is
+ *   reported as a conflict and refused instead of guessed;
+ * - every write is atomic (temp sibling + rename) and never crosses a reparse
+ *   point;
+ * - the whole-home scan never descends a reparse point: with plain `lstat` a
+ *   symlink/junction reports as a link, and other reparse flavours still fall
+ *   under the runner's own Win32-attribute preflight, which remains the
+ *   authoritative gate;
+ * - the command sets configuration — it never deletes `node_modules`, never
+ *   runs pnpm, and never repairs ACLs or ownership written in the past.
+ *
+ * @module profile-isolation
+ */
+/**
+ * Mirrors `PROFILE_PNPM_WORKSPACE` written by `initProfile` in
+ * `@deepseek-ai/dsh-app-boot`; that constant is not exported, so the template
+ * is duplicated here and must stay in sync with upstream.
+ */
+export declare const PROFILE_PNPM_WORKSPACE = "packages:\n  - .\n\nnodeLinker: hoisted\nautoInstallPeers: false\n";
+/** One accepted top-level `key: value` line, located in the source text. */
+export interface WorkspaceYamlEntry {
+    /** The unquoted scalar when the value is one; `undefined` for block/complex. */
+    readonly value: string | undefined;
+    /**
+     * `scalar` — a same-line plain or quoted scalar; `block` — the value is
+     * empty, so a nested block (or an explicit comment) follows; `complex` —
+     * the value opens with a YAML node property or collection marker
+     * (`&`, `*`, `!`, `|`, `>`, `{`, `[`) or is a malformed scalar the subset
+     * refuses to interpret.
+     */
+    readonly kind: 'scalar' | 'block' | 'complex';
+    /** 1-based line number the key sits on. */
+    readonly line: number;
+    /** UTF-16 code-unit offset where the value token begins. */
+    readonly valueStart: number;
+    /** UTF-16 code-unit offset just past the value token (before ` #comment` or EOL). */
+    readonly valueEnd: number;
+}
+/**
+ * Read the top-level `key: value` lines of a `pnpm-workspace.yaml` text.
+ *
+ * This is a strict subset scanner, deliberately NOT a YAML parser: it accepts
+ * only top-level `key:` lines (plain or quoted keys) plus indented nested
+ * content it never interprets, and throws — naming the file and the 1-based
+ * line — on an indented first entry, tabs in indentation, `%` / `---` / `...` directives, duplicate
+ * top-level keys, or any other non-indented content line outside the key
+ * form. A `#` preceded by whitespace ends a plain scalar; quoted scalars are
+ * unquoted for the reported value. `valueStart`/`valueEnd` are the UTF-16
+ * offsets of the value token itself, so a caller can replace exactly the
+ * scalar while comments and line endings survive untouched.
+ *
+ * @param text - the yaml text to scan.
+ * @param path - the file name used in rejection messages.
+ * @returns the top-level entries keyed by their unquoted names.
+ */
+export declare function parseWorkspaceYamlKeys(text: string, path?: string): ReadonlyMap<string, WorkspaceYamlEntry>;
+/** What one confirmed profile's `pnpm-workspace.yaml` says about imports. */
+export interface ProfileYamlReport {
+    /**
+     * `absent` — `packageImportMethod` is not configured (the file may still
+     * exist); `copy` — it is a same-line scalar `copy`; `conflict` — it exists
+     * but is not a plain `copy` scalar, or the yaml exists but is a reparse
+     * point / non-file; `unreadable` — the file cannot be read or the subset
+     * scanner rejected it.
+     */
+    readonly state: 'absent' | 'copy' | 'conflict' | 'unreadable';
+    /** Human-readable reason for `conflict`/`unreadable`. */
+    readonly detail?: string;
+}
+/** One confirmed profile and its yaml verdict. */
+export interface ProfileReport {
+    /** The profile directory name under `profiles/`. */
+    readonly name: string;
+    /** The profile's absolute path under the canonical home. */
+    readonly path: string;
+    /** The `packageImportMethod` verdict for its workspace yaml. */
+    readonly yaml: ProfileYamlReport;
+}
+/** The read-only whole-home scan accompanying every report. */
+export interface HomeScan {
+    /** Directories successfully listed (including the home itself). */
+    readonly directories: number;
+    /** Non-directory entries inspected — plain files and reparse leaves alike. */
+    readonly files: number;
+    /** Plain files carrying more than one name (`st_nlink > 1`). */
+    readonly multiLinkTotal: number;
+    /** Up to {@link SAMPLE_CAP} absolute paths of multi-link files. */
+    readonly multiLinkPaths: readonly string[];
+    /** Entries `lstat`/`readdir` failed on (first {@link SAMPLE_CAP}). */
+    readonly uninspectable: readonly {
+        path: string;
+        reason: string;
+    }[];
+    /** Total uninspectable entries — may exceed the retained paths. */
+    readonly uninspectableTotal: number;
+}
+/** The read-only verdict for one canonical home. */
+export interface IsolateReport {
+    /** The canonical DSH home the report covers. */
+    readonly home: string;
+    /** Confirmed profiles only; non-profile entries are listed separately. */
+    readonly profiles: readonly ProfileReport[];
+    /** `profiles/` entries that are not confirmed profiles — never written. */
+    readonly nonProfileEntries: readonly string[];
+    /** The whole-home link/uninspectable counts. */
+    readonly scan: HomeScan;
+    /** True whenever anything could not be inspected — never a clean result. */
+    readonly incomplete: boolean;
+}
+/** The per-profile outcome of one `--apply` run. */
+export interface ProfileAction {
+    readonly name: string;
+    /**
+     * `written` — the yaml was created or gained the key; `replaced` — a
+     * same-line scalar was swapped in place; `noop` — already `copy`;
+     * `refused` — a conflict/unreadable file the command will not guess at.
+     */
+    readonly action: 'written' | 'replaced' | 'noop' | 'refused';
+    readonly detail?: string;
+}
+/** The report of one `--apply` run: the read verdict plus the actions. */
+export interface ApplyReport extends IsolateReport {
+    readonly actions: readonly ProfileAction[];
+}
+/**
+ * Read-only inspection of a DSH home: confirmed profiles under `profiles/`,
+ * each one's `packageImportMethod` verdict, and a whole-home `lstat` scan
+ * counting directories, files, multi-link files, and uninspectable entries.
+ * Nothing is written. The report is `incomplete` — never clean — whenever any
+ * entry could not be inspected.
+ * @param home - the DSH home to inspect (canonicalized).
+ * @returns the isolation report.
+ */
+export declare function isolateReport(home: string): IsolateReport;
+/**
+ * Write `packageImportMethod: copy` into every fixable confirmed profile.
+ * A missing file receives the upstream profile template plus the copy line;
+ * a missing key is appended; a same-line non-`copy` scalar is replaced by
+ * byte range so comments and CRLF survive; a block/complex/duplicate-key or
+ * unreadable file is refused untouched. Every write lands atomically through
+ * a sibling temp file + rename, and the command never descends or writes
+ * through a reparse point.
+ * @param home - the DSH home to migrate (canonicalized).
+ * @returns the read verdict plus one action per confirmed profile.
+ */
+export declare function applyIsolateConfig(home: string): ApplyReport;
+/**
+ * The remediation steps the user must run by hand — this command writes
+ * configuration only. For every confirmed profile whose dependencies still
+ * need re-installing as copies (config changed under it, or links were seen
+ * inside it), the steps say: quit the hosts using it, remove its
+ * `node_modules` yourself, reinstall from its lockfile. Refused profiles get
+ * a manual-resolution line instead of automated steps.
+ * @param report - the {@link ApplyReport} (or a check report) to explain.
+ * @returns the guidance lines, in English.
+ */
+export declare function remediationSteps(report: IsolateReport): string[];

package/lib/types/providers.d.ts

@@ -0,0 +1,70 @@
+/**
+ * `MultiRootProviders`: the fail-loud guard that proves the services mounted as
+ * `ctx.fs` and `ctx.sandbox` are THIS bundle's providers — the only ones whose
+ * widening the registry, the instruction row, LSP routing and workspace-files
+ * are allowed to attach to.
+ *
+ * Why a brand and not `instanceof`: the plugin may be installed twice (a
+ * duplicated install forks the class identity), and cordis private fields are
+ * not a public contract. A well-known symbol survives both. The brand is
+ * non-enumerable so it never leaks into spreads, JSON, or surface payloads.
+ *
+ * Deterministic outcome under a provider conflict: cordis refuses a second
+ * `ctx.provide` of an already-registered key, so whoever mounts the colliding
+ * provider second loses loudly — but a conflicting plugin can also DISABLE this
+ * bundle's rows (the same mechanism this bundle uses on upstream), leaving a
+ * foreign `ctx.fs`/`ctx.sandbox` in place. In that case this service's
+ * `[Service.init]` logs which service is foreign and throws: the row never
+ * activates, so every row injecting `multiRootProviders` — the registry above
+ * all — never starts, the scope stays empty, and nothing is ever granted,
+ * regardless of patch order. Cordis re-evaluates an injecting fiber when an
+ * injected service is unprovided and re-provided, so a LATE replacement re-runs
+ * the same check.
+ *
+ * @module @dsh-electron/dsh-plugin-multi-root-workspace/providers
+ */
+import { Service } from '@deepseek-ai/cordis';
+/**
+ * The well-known brand key both providers carry. `Symbol.for` makes it
+ * identical across duplicated installs of this package.
+ */
+export declare const MULTI_ROOT_PROVIDER_BRAND: unique symbol;
+/** The two service keys this bundle takes over. */
+export type ProviderKind = 'fs' | 'sandbox';
+/**
+ * Stamp the multi-root provider brand on a service value. Non-enumerable:
+ * the mark must not travel into structural copies.
+ * @param value - the service instance being mounted.
+ * @param kind - which provider key it claims.
+ * @returns the same value, branded.
+ */
+export declare function brandMultiRootProvider<T>(value: T, kind: ProviderKind): T;
+/**
+ * Whether `value` is this bundle's provider of `kind`. Structural on purpose:
+ * no `instanceof`, so a duplicated install still recognizes the brand.
+ * @param value - the service mounted under the key.
+ * @param kind - the provider key being checked.
+ */
+export declare function isMultiRootProvider(value: unknown, kind: ProviderKind): boolean;
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        multiRootProviders: MultiRootProviders;
+    }
+}
+/**
+ * The conflict gate: `ctx.multiRootProviders` exists only while `ctx.fs` and
+ * `ctx.sandbox` are this bundle's branded providers. Every row that widens an
+ * authority surface injects it, so a foreign provider composition loses the
+ * whole gated set instead of silently widening an unverified one.
+ */
+export declare class MultiRootProviders extends Service {
+    static provide: string;
+    static inject: string[];
+    /**
+     * Verify the provider identities once per activation. A foreign service is
+     * named in the log and the throw leaves this row — and every dependent —
+     * unstarted: fail loud, never a widened grant.
+     */
+    protected [Service.init](): void;
+}
+export default MultiRootProviders;

package/lib/types/registry.d.ts

@@ -37,14 +37,15 @@
  *   memory-authoritative after open, so two DSH processes sharing a storage
  *   root cannot each keep a live domain snapshot. A store-wide kernel lease
  *   (ADR-0007) elects one authority; a contended process publishes an empty
- *   scope, rejects mutations, and retries the lease from {@link MultiRootRegistry.refresh}.
+ *   scope marked `authority: 'unavailable'` — under which Full-access is
+ *   limited to primary-root-only writes — rejects mutations, and retries the lease
+ *   from {@link MultiRootRegistry.refresh}.
  *
  * @module @dsh-electron/dsh-plugin-multi-root-workspace/registry
  */
 import { Context, Service } from '@deepseek-ai/cordis';
 import type { SandboxExecutionPolicy } from '@deepseek-ai/dsh-sandbox';
-import { z } from 'zod';
-import { type AdditionalRootId, type RegisteredRoot, type RootRef, type RootStatus } from './roots.ts';
+import { type AdditionalRootId, type RegisteredRoot, type RootAccess, type RootRef, type RootStatus } from './roots.ts';
 /** The domain name; also the store file stem (`$DSH_HOME/storages/<name>.json`). */
 export declare const DOMAIN_NAME = "multi_root_workspace";
 /** The single table name inside the domain. */
@@ -56,10 +57,20 @@ export declare const MAX_ALIAS_LENGTH = 120;
  * locale; the panel also shows this string verbatim via `RootsView.unavailable`.
  */
 export declare const REGISTRY_CONTENDED_MESSAGE = "the root registry is owned by another DSH process; additional roots are not granted here. Close the other process, then retry.";
+/**
+ * Default cap on stored additional-root records per primary root. The bench
+ * evidence for this default lives in `docs/reference/bench-root-scale-*.json`
+ * (`pnpm bench:roots`): classification and argv widening stay flat far beyond
+ * it, so the cap exists to bound the operator-facing list and the widened
+ * profile size, not to protect the classifier.
+ */
+export declare const DEFAULT_MAX_ADDITIONAL_ROOTS = 16;
+/** Hard ceiling for `maxAdditionalRoots`: values above it are config-invalid. */
+export declare const MAX_ADDITIONAL_ROOTS_CEILING = 64;
 /**
  * Whether this process is the Registry Authority for the store-wide domain
  * medium. Contended and storage-failed are both fail-closed: the scope stays
- * empty and mutations reject.
+ * empty, is marked `authority: 'unavailable'`, and mutations reject.
  */
 export type RegistryAuthorityState = {
     readonly kind: 'active';
@@ -68,6 +79,9 @@ export type RegistryAuthorityState = {
 } | {
     readonly kind: 'storage-failed';
     readonly reason: string;
+} | {
+    readonly kind: 'config-invalid';
+    readonly reason: string;
 };
 /**
  * Plugin configuration for the registry row. `leasePath` must sit beside the
@@ -78,6 +92,16 @@ export type RegistryAuthorityState = {
 export interface Config {
     /** Absolute path of the store-wide kernel lock file. */
     readonly leasePath?: string;
+    /**
+     * Cap on STORED additional-root records per primary root (every state
+     * counts, including withheld and unusable ones, so the count is stable and
+     * independent of the filesystem). Must be an integer in
+     * 1..{@link MAX_ADDITIONAL_ROOTS_CEILING}; an invalid value puts the
+     * registry in the fail-closed `config-invalid` state instead of throwing.
+     * A store that already exceeds the limit keeps every record and grants
+     * exactly what classification grants — only new adds are refused.
+     */
+    readonly maxAdditionalRoots?: number;
 }
 declare module '@deepseek-ai/cordis' {
     interface Context {
@@ -85,21 +109,54 @@ declare module '@deepseek-ai/cordis' {
     }
 }
 /**
- * One primary root's whole registration list. The domain's `single` layout
- * stores the entire unit as one document, so keys stay opaque strings — which
- * is exactly what lets the canonical primary root itself be the key.
+ * Stored shape of one root record.
+ *
+ * The access level is expressed by WHICH grant key is present, never by an
+ * `access` field on the same `recordedPath` (ADR-0017):
+ *
+ * - `recordedPath` means `inherit` — the historical writable grant, which
+ *   under B9 keeps following the session mode. Upgrading a legacy record to
+ *   `inherit` changes nothing about its effective authority.
+ * - `readOnlyRecordedPath` means `read-only`.
+ * - `readWriteRecordedPath` means fixed `read-write` (B9).
+ *
+ * That split is what makes this single layout downgrade-safe at domain
+ * version 1 (the JSON backend checks the version with strict equality, so a
+ * bump would break both upgrade and downgrade):
+ *
+ * - an OLDER plugin version parses this record with a schema that strips
+ *   unknown keys, so a read-only or fixed read-write record loses its grant
+ *   field and arrives with NO `recordedPath`; the old classification reports
+ *   it `invalid` and grants nothing — a downgrade can never escalate either
+ *   restricted level into a write grant. A fixed read-write record must
+ *   therefore NEVER also write `recordedPath`: an older plugin would see the
+ *   legacy field and grant it as plain read-write;
+ * - a record with `recordedPath` only is the writable grant it always was,
+ *   so upgrading changes nothing for legacy records.
  */
-declare const persistedPrimaryRoot: z.ZodObject<{
-    roots: z.ZodArray<z.ZodObject<{
-        id: z.ZodString;
-        path: z.ZodString;
-        recordedPath: z.ZodOptional<z.ZodString>;
-        alias: z.ZodOptional<z.ZodString>;
-        addedAt: z.ZodString;
-    }, z.core.$strip>>;
-}, z.core.$strip>;
-/** Stored shape of one primary root's records. */
-export type PersistedPrimaryRoot = z.infer<typeof persistedPrimaryRoot>;
+type PersistedRoot = {
+    id: string;
+    path: string;
+    /**
+     * Absent only in records written before the field existed (or by hand),
+     * and in non-inherit records. Such a record is reported `invalid` rather
+     * than granted on a guess — see classifyStoredRoots.
+     */
+    recordedPath?: string | undefined;
+    readOnlyRecordedPath?: string | undefined;
+    readWriteRecordedPath?: string | undefined;
+    alias?: string | undefined;
+    addedAt: string;
+};
+/**
+ * Stored shape of one primary root's records: the whole registration list.
+ * The domain's `single` layout stores the entire unit as one document, so
+ * keys stay opaque strings — which is exactly what lets the canonical
+ * primary root itself be the key.
+ */
+export type PersistedPrimaryRoot = {
+    roots: PersistedRoot[];
+};
 /**
  * The domain declaration: version 1, `single` layout, one `roots` table keyed
  * by the canonical primary root. Records that fail validation are backed up and
@@ -111,15 +168,7 @@ export declare const multiRootDomainSpec: {
     version: number;
     invalidRecords: "backup-and-skip";
     tables: {
-        roots: import("@deepseek-ai/dsh-storage-domain").DomainTableSpec<string, {
-            roots: {
-                id: string;
-                path: string;
-                addedAt: string;
-                recordedPath?: string | undefined;
-                alias?: string | undefined;
-            }[];
-        }>;
+        roots: import("@deepseek-ai/dsh-storage-domain").DomainTableSpec<string, PersistedPrimaryRoot>;
     };
 };
 /** Registration request for one new additional root. */
@@ -128,6 +177,12 @@ export interface AddRootInput {
     readonly path: string;
     /** Optional display alias. */
     readonly alias?: string;
+    /**
+     * The write authority to register; defaults to `inherit` (the historical
+     * session-following grant). On a REVIVE the existing record keeps its
+     * access unless this field is given explicitly.
+     */
+    readonly access?: RootAccess;
 }
 /** The registry service: `ctx.multiRootRegistry`. */
 export declare class MultiRootRegistry extends Service {
@@ -156,9 +211,13 @@ export declare class MultiRootRegistry extends Service {
     private loggedContended;
     /** True once the fiber disposer has run: no further acquisition may happen. */
     private disposed;
+    /** The validated per-primary-root cap (the default when the row omits it). */
+    private readonly maxRoots;
+    /** Keys already warned about a historical over-limit store (one warning each). */
+    private readonly warnedOverLimit;
     /**
      * @param ctx - the host context; `storageDomain` and `multiRootScope` are injected.
-     * @param config - the patch row's `leasePath`.
+     * @param config - the patch row's `leasePath` and `maxAdditionalRoots`.
      */
     constructor(ctx: Context, config?: Config);
     /**
@@ -185,6 +244,17 @@ export declare class MultiRootRegistry extends Service {
      * Tests and diagnostics read this; surfaces use {@link unavailable}.
      */
     get authority(): RegistryAuthorityState;
+    /**
+     * The configured cap on stored additional-root records per primary root.
+     * Surfaces show it next to the count so "N of LIMIT" is always explainable.
+     */
+    get limit(): number;
+    /**
+     * Whether one primary root's stored record count exceeds {@link limit} — a
+     * historical over-limit store, which stays fully classified and granted.
+     * @param primaryRoot - the session workspace root (any spelling).
+     */
+    overLimit(primaryRoot: string): boolean;
     /**
      * Every registration of one primary root, in registry order, as last
      * classified. A READ of the in-memory state: it never touches the filesystem
@@ -225,6 +295,29 @@ export declare class MultiRootRegistry extends Service {
      * @throws {RootValidationError} when the candidate violates a root rule.
      */
     add(primaryRoot: string, input: AddRootInput): Promise<readonly RootStatus[]>;
+    /**
+     * Change one registration's write authority WITHOUT re-recording its path.
+     *
+     * Re-resolving is not re-authorizing: the grant keeps the canonical
+     * directory it was recorded for; only which persisted field carries it
+     * changes. The three levels are not a total order — `inherit` is weaker
+     * than `read-write` under a read-only session but stronger under
+     * Full-access — so "upgrade" cannot be a single direction. The gate is
+     * therefore: pinning to `read-only` is always allowed (a withheld root may
+     * be restricted while it is withheld), while ANY other target requires the
+     * root to be `available` under the FRESH classification — every
+     * non-read-only level can widen authority under some session mode, and a
+     * root that is not currently granted must not be granted anything by a
+     * metadata change.
+     * @param primaryRoot - the session workspace root the root belongs to.
+     * @param ref - which registered root to change.
+     * @param access - the new write authority.
+     * @returns the updated status list.
+     * @throws {RootValidationError} `not-found` when the reference matches
+     *   nothing, `root-unavailable` when the target is not `available` and the
+     *   new level is not `read-only`.
+     */
+    setAccess(primaryRoot: string, ref: RootRef, access: RootAccess): Promise<readonly RootStatus[]>;
     /**
      * Remove one registration.
      * @param primaryRoot - the session workspace root the root belongs to.
@@ -329,13 +422,21 @@ export declare class MultiRootRegistry extends Service {
     /**
      * Push one status list into the scope and notify listeners.
      *
-     * What is published is the effective GRANT — only `available` roots, so a
-     * withheld registration can never reach a provider. When the grant and the
-     * withheld set are unchanged (the common case for a read-path refresh on a
+     * What is published is the effective GRANT — membership requires
+     * `available`, so a withheld registration can never reach a provider as a
+     * grant. Withheld entries still publish for their DENY boundary alone;
+     * that includes `membership-conflict` records, whose recorded grant is
+     * intact and trustworthy even though their membership cannot stand. When
+     * the grant and the withheld set are unchanged (the common case for a
+     * read-path refresh on a
      * healthy workspace) the scope is left alone and no listener fires: a refresh
      * exists to keep the two in sync, not to churn on every listing — and, since
      * the scope rebuilds its root table on each call, skipping the no-op write is
      * also what keeps the read path cheap.
+     *
+     * Available roots keep registry order: instruction discovery consumes them
+     * under a shared byte budget, so a move must update the live scope immediately.
+     * Aliases and no-op moves still leave the signature unchanged.
      */
     private publish;
     /**