@aefree/pi-plastic 0.4.0 → 0.5.0

package/skills/using-plastic/SKILL.md

@@ -16,9 +16,9 @@ Treat `plastic_merge` success as provisional until `plastic_status` confirms the
 
 For the common closeout flow of merging a finished source branch into its parent branch, prefer `plastic_mergeToBranch` when available. When `target` is omitted, it resolves the source branch's Plastic parent branch instead of assuming `/dev`. It switches to the target, optionally updates, runs the safe merge, checks merge state, and checks in the merge result. Pass `target` only when the user explicitly wants a different integration branch.
 
-`plastic_diff` is intentionally disabled. For the common workspace change, use `plastic_diffFile(path="<workspace-path>")` with no revision; it materializes the Plastic base internally and returns a bounded portable text diff. Use a revision only when needed: a changeset number/`cs:<number>`, `br:/<branch>`, `lb:<label>`, file-qualified spec, or global `revid:`/`rev:` spec. `base`, `head`, and `cs:head` are intentionally rejected rather than guessed. Use `plastic_diffRevisions` only for two explicit file-qualified revisions. Binary content is reported rather than decoded as text.
+`plastic_diff` is intentionally disabled. Route changed-path listing to `plastic_status()`, one workspace file to `plastic_diffFile(path="<workspace-path>")`, pending review to `plastic_workspaceDiff()`, and an explicit historical pair to `plastic_diffRevisions`. `plastic_diffFile` uses machine-readable status: added and explicitly selected private/new files compare against an empty base; changed, moved, and deleted items use their reported base revision when available. A `--nodata` base failure means Plastic cannot provide historical bytes; refresh/update the workspace or use two known file-qualified revisions. Explicit `revision` behavior remains a separate historical request. Binary content is reported rather than decoded as text.
 
-Use `plastic_status()` for “what changed?” and changed-path/status listing; do not use `cm diff` formatting for that purpose. Use `plastic_patch` for review patch generation with `clean` and `integration` filters; it is generation-only and does not apply patches. It uses `PI_PLASTIC_DIFF_EXECUTABLE` when set, otherwise portable `diff` on PATH; pass `toolPath` only for an intentional one-call override. For a large patch, pass an intentional new `output` path because Plastic will not overwrite it.
+`plastic_workspaceDiff` runs status once, has intentional file/per-file/combined-output bounds, and returns per-file outcomes without aborting when one file is unavailable. It excludes private files by default; select their paths explicitly or pass `includePrivate=true` only when intentional. Use `plastic_patch` for review patch generation with `clean` and `integration` filters; it is generation-only and does not apply patches. It uses `PI_PLASTIC_DIFF_EXECUTABLE` when set, otherwise GNU/POSIX `diff` on PATH; paths containing spaces are supported, but Pi does not discover Git Bash paths automatically. Pass `toolPath` only for an intentional one-call override. For a large patch, pass an intentional new `output` path because Plastic will not overwrite it.
 
 Prefer runtime `plastic_*` tools first. Keep `cm` shell commands as manual fallback.
 

package/skills/using-plastic/references/changeset-operations.md

@@ -77,7 +77,8 @@ Use one of these safe alternatives:
 
 ```text
 plastic_status(machineReadable=true) # list pending paths/statuses
-plastic_diffFile(path="<workspace-path>") # common workspace-base diff
+plastic_diffFile(path="<workspace-path>") # one workspace file
+plastic_workspaceDiff() # bounded pending review; excludes private unless selected/opted in
 plastic_diffFile(path="<workspace-path>", revision="cs:<number>")
 plastic_diffRevisions(leftRevision="<left-file-qualified-revspec>", rightRevision="<right-file-qualified-revspec>")
 ```

package/skills/using-plastic/references/code-review-creation.md

@@ -1,30 +1,30 @@
-# Code Review Creation
-
-## CLI (Preferred)
-
-```bash
-branch=$(cm status | head -1 | cut -d@ -f1 | xargs)
-review_id=$(cm codereview "br:${branch}" "Feature: Brief description" --format="{id}")
-
-# Assign reviewer immediately after creating the review
-cm codereview -e "$review_id" --reviewer="reviewer-name"
-
-# List reviews for this branch
-cm find review "where target='br:${branch}'" --format="{id} {status} {title}"
-```
-
-Agent preference: use runtime `plastic_*` methods first for status/branch lookup; keep shell commands as manual fallback.
-
-Reviewer assignment is required in the workflow. If your server uses different reviewer flags, run `cm codereview --help` and use the server-specific reviewer option right after review creation.
-
-Tool-first flow (preferred):
-
-```text
-plastic_status()
-# Then use cm codereview ... as fallback for review create/assign
-```
-
-## CLI Not Available
-
-- Document branch and changeset in plan/issue tracker.
-- Or create review via Plastic GUI and assign a reviewer before sharing the review link.
+# Code Review Creation
+
+## CLI (Preferred)
+
+```bash
+branch=$(cm status | head -1 | cut -d@ -f1 | xargs)
+review_id=$(cm codereview "br:${branch}" "Feature: Brief description" --format="{id}")
+
+# Assign reviewer immediately after creating the review
+cm codereview -e "$review_id" --reviewer="reviewer-name"
+
+# List reviews for this branch
+cm find review "where target='br:${branch}'" --format="{id} {status} {title}"
+```
+
+Agent preference: use runtime `plastic_*` methods first for status/branch lookup; keep shell commands as manual fallback.
+
+Reviewer assignment is required in the workflow. If your server uses different reviewer flags, run `cm codereview --help` and use the server-specific reviewer option right after review creation.
+
+Tool-first flow (preferred):
+
+```text
+plastic_status()
+# Then use cm codereview ... as fallback for review create/assign
+```
+
+## CLI Not Available
+
+- Document branch and changeset in plan/issue tracker.
+- Or create review via Plastic GUI and assign a reviewer before sharing the review link.

package/skills/using-plastic/references/integration.md

@@ -37,7 +37,8 @@ plastic_patch(source="<branch-spec>", clean=true, integration=true, output="<pat
 - Inspect specific file content changes with the common workspace-base path first:
 
 ```text
-plastic_diffFile(path="<workspace-path>")
+plastic_diffFile(path="<workspace-path>") # one workspace file
+plastic_workspaceDiff() # bounded pending review
 plastic_diffFile(path="<workspace-path>", revision="cs:<number>")
 plastic_diffRevisions(leftRevision="<left-file-qualified-revspec>", rightRevision="<right-file-qualified-revspec>")
 ```

package/skills/using-plastic/references/quick-reference.md

@@ -18,7 +18,8 @@ Note: command examples target current `cm` 11.x CLI syntax; legacy aliases may d
 | Shelve | `plastic_shelvesetCreate(comment="description")` | `cm shelveset create -c="description"` | Save work temporarily |
 | Patch for review | `plastic_patch(source="<branch-spec>", clean=true, integration=true, output="<patch-file>")` | `cm patch <branch-spec> --clean --integration --output=<patch-file>` | Focused branch-review patch; inspect before sharing |
 | Changed-file listing | `plastic_status(machineReadable=true)` | `cm status --all` | Lists changed, added, moved, deleted, and private items without GUI diff |
-| Diff (workspace vs Plastic base) | `plastic_diffFile(path="<workspace-path>")` | None recommended | Bounded portable text diff; no guessed revision needed |
+| Diff (one workspace file) | `plastic_diffFile(path="<workspace-path>")` | None recommended | Uses status base materialization; added/private files use an empty base |
+| Diff (pending review) | `plastic_workspaceDiff()` | None recommended | Runs status once; bounded per-file outcomes; private files excluded unless selected/opted in |
 | Diff (workspace vs supported revision) | `plastic_diffFile(path="<workspace-path>", revision="cs:<number>")` | None recommended | Also accepts a branch, label, file-qualified, or global revision spec |
 | Diff (revision vs revision) | `plastic_diffRevisions(leftRevision="<left-revspec>", rightRevision="<right-revspec>")` | None recommended | Requires two file-qualified revisions; avoids GUI and package temp-file recipes |
 

package/skills/using-plastic/references/resources.md

@@ -1,7 +1,7 @@
-# Resources
-
-- CLI Reference: https://docs.unity.com/en-us/unity-version-control/uvcs-cli
-- Branch Management: https://docs.unity.com/en-us/unity-version-control/branches
-- Code Reviews: https://docs.unity.com/en-us/unity-version-control/code-reviews
-
-Minimum version: PlasticSCM 11.0+
+# Resources
+
+- CLI Reference: https://docs.unity.com/en-us/unity-version-control/uvcs-cli
+- Branch Management: https://docs.unity.com/en-us/unity-version-control/branches
+- Code Reviews: https://docs.unity.com/en-us/unity-version-control/code-reviews
+
+Minimum version: PlasticSCM 11.0+

package/skills/using-plastic/references/reviewing-changes.md

@@ -25,12 +25,13 @@ Prefer tool-first:
 
 ```text
 plastic_status(machineReadable=true) # “what changed?” / changed-path listing
-plastic_diffFile(path="<workspace-path>") # common workspace vs Plastic-base comparison
-plastic_diffFile(path="<workspace-path>", revision="cs:<number>") # explicit advanced comparison
+plastic_diffFile(path="<workspace-path>") # one workspace file
+plastic_workspaceDiff() # bounded pending review; private files excluded by default
+plastic_diffFile(path="<workspace-path>", revision="cs:<number>") # explicit historical comparison
 plastic_diffRevisions(leftRevision="<left-file-qualified-revspec>", rightRevision="<right-file-qualified-revspec>")
 ```
 
-The diff tools materialize historical bytes and remove their temporary files internally. They use a bounded portable text diff, treat valid Unity YAML as text, and report genuine binary content explicitly. Do not construct `cm cat` temporary-file recipes for ordinary review.
+The diff tools materialize historical bytes and remove their temporary files internally. Added and explicitly selected private/new files use an empty base; changed, moved, and deleted records use their status revision ID when available. A `--nodata` item cannot supply historical/base bytes: refresh the workspace or use two known file-qualified revisions. `plastic_workspaceDiff` returns per-file unavailable outcomes instead of aborting the batch. All tools use bounded GNU/POSIX text diff, treat valid Unity YAML as text, and report genuine binary content explicitly. Do not construct `cm cat` temporary-file recipes for ordinary review.
 
 ## Metadata Listing (No GUI Diff)
 

package/skills/using-plastic/references/shelving.md

@@ -1,25 +1,25 @@
-# Shelving
-
-## Save Work
-
-```bash
-cm shelveset create -c="Working on feature X"
-```
-
-## List Shelves
-
-```bash
-cm find shelve "where owner='me'" --format="{shelveid} {date} {comment}"
-```
-
-## Restore Work
-
-```bash
-cm shelveset apply sh:5
-```
-
-## Delete Shelve
-
-```bash
-cm shelveset delete sh:5
-```
+# Shelving
+
+## Save Work
+
+```bash
+cm shelveset create -c="Working on feature X"
+```
+
+## List Shelves
+
+```bash
+cm find shelve "where owner='me'" --format="{shelveid} {date} {comment}"
+```
+
+## Restore Work
+
+```bash
+cm shelveset apply sh:5
+```
+
+## Delete Shelve
+
+```bash
+cm shelveset delete sh:5
+```

package/skills/using-plastic/references/troubleshooting.md

@@ -41,7 +41,8 @@ cm codereview -e <review-id> --reviewer="reviewer-name"
 - `cm diff` is blocked in Pi because it can launch GUI windows and hang the CLI.
 - Use text-only alternatives:
   - `plastic_status(machineReadable=true)` for changed paths/statuses.
-  - `plastic_diffFile(path="<workspace-path>")` for the common workspace-base comparison.
+  - `plastic_diffFile(path="<workspace-path>")` for one workspace file.
+  - `plastic_workspaceDiff()` for bounded pending review (private files are excluded unless selected/opted in).
   - `plastic_diffFile(path="<workspace-path>", revision="cs:<number>")` for an explicit supported revision.
   - `plastic_diffRevisions(leftRevision="<left-file-qualified-revspec>", rightRevision="<right-file-qualified-revspec>")` for two historical files.
 

package/skills/using-plastic/references/workspaces.md

@@ -1,33 +1,33 @@
-# Review Workspaces
-
-## Strategy
-
-- Use a separate review workspace for isolation.
-- Reuse `-review-1` by default (Unity workspaces are large).
-
-## Create or Reuse
-
-```bash
-main_workspace=$(basename "$PWD")
-review_workspace_name="${main_workspace}-review-1"
-review_workspace="../${review_workspace_name}"
-
-if [ -d "$review_workspace" ]; then
-  cd "$review_workspace"
-  cm switch --silent --noinput "$review_branch" || {
-    cm shelveset create --all -c="Auto-shelve before review switch"
-    cm switch --silent --noinput "$review_branch"
-  }
-else
-  repo_spec=$(cm status --wkconfig | grep "^Repository:" | cut -d: -f2- | xargs)
-  cm workspace create "$review_workspace_name" "$review_workspace" "$repo_spec"
-  cd "$review_workspace"
-  cm switch --silent --noinput "$review_branch"
-fi
-```
-
-Agent preference: use runtime `plastic_*` methods first for branch/status operations; keep shell commands as manual fallback.
-
-## Cleanup
-
-Only remove review workspaces when disk space is tight or requested.
+# Review Workspaces
+
+## Strategy
+
+- Use a separate review workspace for isolation.
+- Reuse `-review-1` by default (Unity workspaces are large).
+
+## Create or Reuse
+
+```bash
+main_workspace=$(basename "$PWD")
+review_workspace_name="${main_workspace}-review-1"
+review_workspace="../${review_workspace_name}"
+
+if [ -d "$review_workspace" ]; then
+  cd "$review_workspace"
+  cm switch --silent --noinput "$review_branch" || {
+    cm shelveset create --all -c="Auto-shelve before review switch"
+    cm switch --silent --noinput "$review_branch"
+  }
+else
+  repo_spec=$(cm status --wkconfig | grep "^Repository:" | cut -d: -f2- | xargs)
+  cm workspace create "$review_workspace_name" "$review_workspace" "$repo_spec"
+  cd "$review_workspace"
+  cm switch --silent --noinput "$review_branch"
+fi
+```
+
+Agent preference: use runtime `plastic_*` methods first for branch/status operations; keep shell commands as manual fallback.
+
+## Cleanup
+
+Only remove review workspaces when disk space is tight or requested.

package/src/file-discovery-filter-rendezvous.ts

@@ -0,0 +1,104 @@
+/**
+ * Narrow local adapter for the published capability-registry global protocol.
+ *
+ * Pi loads independently installed packages from separate module roots. Plastic
+ * therefore registers its optional file-discovery filter through the stable
+ * global capability key instead of importing a sibling package contract.
+ */
+const ROOT_PROTOCOL = "@aefree/pi-capability-registry/root";
+const ROOT_PROTOCOL_VERSION = 1;
+export const PLASTIC_FILE_DISCOVERY_FILTER_REGISTRY_KEY_V1 = "@aefree/pi-file-discovery/filters/v1" as const;
+
+type FilterOwner = Readonly<{ packageName: string; packageRoot: string }>;
+type FilterRecord = Readonly<{ contractVersion: 1; id: string; kind: "file-discovery-filter"; owner: FilterOwner; evaluate: (...args: never[]) => unknown }>;
+export type PlasticFileDiscoveryRegistrationToken = Readonly<{ registryKey: string; contractVersion: 1; scope: object; ownerKey: string; id: string; nonce: number }>;
+type StoredRecord = Readonly<{ nonce: number; record: FilterRecord }>;
+type ScopedState = { sequence: number; records: Map<string, StoredRecord> };
+type VersionState = { version: 1; scopes: WeakMap<object, ScopedState> };
+type RegistryRoot = { protocol: string; protocolVersion: number; registryKey: string; versions: Map<unknown, unknown> };
+
+export type PlasticFileDiscoveryFilterRegistryV1 = Readonly<{
+  register(scope: object, filter: FilterRecord): PlasticFileDiscoveryRegistrationToken;
+  unregister(token: PlasticFileDiscoveryRegistrationToken | undefined): boolean;
+}>;
+
+/** Create Plastic's view of the shared file-discovery v1 capability registry. */
+export function createPlasticFileDiscoveryFilterRegistryV1(): PlasticFileDiscoveryFilterRegistryV1 {
+  const registryKey = PLASTIC_FILE_DISCOVERY_FILTER_REGISTRY_KEY_V1;
+  const globalRecord = globalThis as typeof globalThis & Record<symbol, unknown>;
+  const symbol = Symbol.for(registryKey);
+  let candidate = globalRecord[symbol];
+  if (candidate === undefined) {
+    candidate = { protocol: ROOT_PROTOCOL, protocolVersion: ROOT_PROTOCOL_VERSION, registryKey, versions: new Map() } satisfies RegistryRoot;
+    globalRecord[symbol] = candidate;
+  }
+  const root = assertRoot(candidate, registryKey);
+  let versionCandidate = root.versions.get(1);
+  if (versionCandidate === undefined) {
+    versionCandidate = { version: 1, scopes: new WeakMap<object, ScopedState>() } satisfies VersionState;
+    root.versions.set(1, versionCandidate);
+  }
+  const version = assertVersionState(versionCandidate, registryKey);
+
+  return Object.freeze({
+    register(scope, filter) {
+      assertScope(scope);
+      assertFilter(filter);
+      let scoped = version.scopes.get(scope);
+      if (scoped === undefined) {
+        scoped = { sequence: 0, records: new Map() };
+        version.scopes.set(scope, scoped);
+      } else {
+        assertScopedState(scoped, registryKey);
+      }
+      const ownerKey = `${filter.owner.packageName}\0${filter.owner.packageRoot}\0${filter.id}`;
+      for (const current of scoped.records.values()) {
+        if (current.record.id === filter.id && ownerKeyFor(current.record) !== ownerKey) {
+          throw new TypeError(`Provider id '${filter.id}' conflicts in file-discovery registry '${registryKey}'.`);
+        }
+      }
+      const nonce = scoped.sequence + 1;
+      scoped.records.set(ownerKey, Object.freeze({ nonce, record: filter }));
+      scoped.sequence = nonce;
+      return Object.freeze({ registryKey, contractVersion: 1, scope, ownerKey, id: filter.id, nonce });
+    },
+    unregister(token) {
+      if (!token || token.registryKey !== registryKey || token.contractVersion !== 1) return false;
+      const scoped = version.scopes.get(token.scope);
+      if (scoped === undefined) return false;
+      assertScopedState(scoped, registryKey);
+      const current = scoped.records.get(token.ownerKey);
+      if (current === undefined || current.nonce !== token.nonce || current.record.id !== token.id) return false;
+      scoped.records.delete(token.ownerKey);
+      return true;
+    },
+  });
+}
+
+function assertRoot(value: unknown, registryKey: string): RegistryRoot {
+  if (value === null || typeof value !== "object") throw incompatible(registryKey);
+  const root = value as Partial<RegistryRoot>;
+  if (root.protocol !== ROOT_PROTOCOL || root.protocolVersion !== ROOT_PROTOCOL_VERSION || root.registryKey !== registryKey || !(root.versions instanceof Map)) throw incompatible(registryKey);
+  return root as RegistryRoot;
+}
+function assertVersionState(value: unknown, registryKey: string): VersionState {
+  if (value === null || typeof value !== "object") throw incompatible(registryKey);
+  const state = value as Partial<VersionState>;
+  if (state.version !== 1 || !(state.scopes instanceof WeakMap)) throw incompatible(registryKey);
+  return state as VersionState;
+}
+function assertScopedState(value: unknown, registryKey: string): asserts value is ScopedState {
+  if (value === null || typeof value !== "object") throw incompatible(registryKey);
+  const state = value as Partial<ScopedState>;
+  if (!Number.isSafeInteger(state.sequence) || (state.sequence ?? -1) < 0 || !(state.records instanceof Map)) throw incompatible(registryKey);
+}
+function assertScope(scope: unknown): asserts scope is object {
+  if ((typeof scope !== "object" && typeof scope !== "function") || scope === null) throw new TypeError("File-discovery registration requires a session scope object.");
+}
+function assertFilter(value: unknown): asserts value is FilterRecord {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) throw new TypeError("Plastic attempted an invalid file-discovery filter registration.");
+  const filter = value as Partial<FilterRecord>;
+  if (filter.contractVersion !== 1 || filter.kind !== "file-discovery-filter" || typeof filter.id !== "string" || !filter.id || typeof filter.evaluate !== "function" || filter.owner === null || typeof filter.owner !== "object" || typeof filter.owner.packageName !== "string" || !filter.owner.packageName || typeof filter.owner.packageRoot !== "string" || !filter.owner.packageRoot) throw new TypeError("Plastic attempted an invalid file-discovery filter registration.");
+}
+function ownerKeyFor(record: FilterRecord): string { return `${record.owner.packageName}\0${record.owner.packageRoot}\0${record.id}`; }
+function incompatible(registryKey: string): TypeError { return new TypeError(`@aefree/pi-file-discovery advertises an incompatible capability-registry contract for '${registryKey}'.`); }

package/src/{repository-search-provider.ts → file-discovery-filter.ts}

@@ -2,23 +2,26 @@ import { access, readFile, realpath, stat } from "node:fs/promises";
 import { constants as fsConstants } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-// Structural copies of the narrow public v1 contract keep the policy module loadable
+// Structural copies of the narrow public v1 contract keep the filter module loadable
 // when the optional registry package is absent. The installed registry validates the
-// record when registration is available.
-type RepoSearchOwnerV1 = Readonly<{ packageName: string; packageVersion: string; packageRoot: string; registeredBy: string }>;
-type RepoSearchExecutionContextV1 = Readonly<{ cwd: string; requestId?: string; signal: AbortSignal }>;
-type RepositoryPolicyRequestV1 = Readonly<{ workspaceRoot: string; roots: readonly string[]; includeHidden: boolean; options?: Readonly<Record<string, unknown>>; signal: AbortSignal }>;
-type RepositoryPolicyResultV1 =
+// record when registration is available; unavailable or malformed filter data
+// degrades to generic discovery rather than interrupting file discovery.
+type FileDiscoveryOwnerV1 = Readonly<{ packageName: string; packageVersion: string; packageRoot: string; registeredBy: string }>;
+type FileDiscoveryExecutionContextV1 = Readonly<{ cwd: string; requestId?: string; signal: AbortSignal }>;
+type FileDiscoveryFilterRequestV1 = Readonly<{ workspaceRoot: string; roots: readonly string[]; includeHidden: boolean; signal: AbortSignal }>;
+type FileDiscoveryAppliedRootV1 = Readonly<{ root: string; filterDecision: "applied" | "bypassed"; decisionCode: string; filterBoundary?: string; excludeGlobs?: readonly string[]; ignoreFiles?: readonly string[]; disclosures: readonly string[] }>;
+type FileDiscoveryFilterResultV1 =
   | Readonly<{ outcome: "not_applicable" }>
-  | Readonly<{ outcome: "applied"; roots: readonly Readonly<{ root: string; policyOwnedRoot?: string; excludeGlobs?: readonly string[]; ignoreFiles?: readonly string[]; disclosures: readonly string[] }>[] }>
+  | Readonly<{ outcome: "applied"; roots: readonly FileDiscoveryAppliedRootV1[] }>
   | Readonly<{ outcome: "unavailable" | "error"; code: string; retryable: boolean }>;
-type RepositoryPolicyV1 = Readonly<{ contractVersion: 1; id: string; kind: "repository-search-policy"; owner: RepoSearchOwnerV1; evaluate(context: RepoSearchExecutionContextV1, request: RepositoryPolicyRequestV1): Promise<RepositoryPolicyResultV1> }>;
+type FileDiscoveryFilterV1 = Readonly<{ contractVersion: 1; id: string; kind: "file-discovery-filter"; owner: FileDiscoveryOwnerV1; evaluate(context: FileDiscoveryExecutionContextV1, request: FileDiscoveryFilterRequestV1): Promise<FileDiscoveryFilterResultV1> }>;
 import { discoverPlasticWorkspace } from "./plastic-workspace.ts";
 
-export const PLASTIC_REPOSITORY_SEARCH_POLICY_ID = "plastic.ignore-files" as const;
+export const PLASTIC_FILE_DISCOVERY_FILTER_ID = "plastic.ignore-files" as const;
+export const PLASTIC_IGNORE_FILES_APPLIED_CODE = "plastic_ignore_files_applied" as const;
 
-/** Resolve this physical package copy's identity for repository-search registration. */
-export async function loadPlasticOwnerV1(moduleUrl: string = import.meta.url): Promise<RepoSearchOwnerV1> {
+/** Resolve this physical package copy's identity for file-discovery registration. */
+export async function loadPlasticOwnerV1(moduleUrl: string = import.meta.url): Promise<FileDiscoveryOwnerV1> {
   const registeredBy = fileURLToPath(moduleUrl);
   const packageRoot = await realpath(fileURLToPath(new URL("../", moduleUrl)));
   const manifest = JSON.parse(await readFile(join(packageRoot, "package.json"), "utf8")) as { name?: unknown; version?: unknown };
@@ -26,13 +29,13 @@ export async function loadPlasticOwnerV1(moduleUrl: string = import.meta.url): P
   return Object.freeze({ packageName: "@aefree/pi-plastic", packageVersion: manifest.version, packageRoot, registeredBy });
 }
 
-/** Independent executable policy for bounded Plastic ignore/cloaking discovery. */
-export function createPlasticRepositorySearchPolicyV1(owner: RepoSearchOwnerV1): RepositoryPolicyV1 {
+/** Advisory filter that supplies bounded Plastic ignore/cloaking data to file discovery. */
+export function createPlasticFileDiscoveryFilterV1(owner: FileDiscoveryOwnerV1): FileDiscoveryFilterV1 {
   return Object.freeze({
-    contractVersion: 1, id: PLASTIC_REPOSITORY_SEARCH_POLICY_ID, kind: "repository-search-policy", owner,
-    async evaluate(context: RepoSearchExecutionContextV1, request: RepositoryPolicyRequestV1): Promise<RepositoryPolicyResultV1> {
+    contractVersion: 1, id: PLASTIC_FILE_DISCOVERY_FILTER_ID, kind: "file-discovery-filter", owner,
+    async evaluate(context: FileDiscoveryExecutionContextV1, request: FileDiscoveryFilterRequestV1): Promise<FileDiscoveryFilterResultV1> {
       throwIfAborted(context.signal);
-      const roots = [] as { root: string; policyOwnedRoot: string; ignoreFiles: string[]; disclosures: string[] }[];
+      const roots: FileDiscoveryAppliedRootV1[] = [];
       for (const root of request.roots) {
         throwIfAborted(context.signal);
         const workspace = await discoverPlasticWorkspace(root);
@@ -42,7 +45,8 @@ export function createPlasticRepositorySearchPolicyV1(owner: RepoSearchOwnerV1):
         const canonicalWorkspace = await realpath(workspace.value.root).catch(() => undefined);
         if (!canonicalRoot || !canonicalWorkspace || !isWithin(canonicalWorkspace, canonicalRoot)) return { outcome: "error", code: "plastic_workspace_boundary_invalid", retryable: false };
         const ignoreFiles = await discoverIgnoreFiles(canonicalWorkspace, canonicalRoot, context.signal);
-        roots.push({ root: canonicalRoot, policyOwnedRoot: canonicalWorkspace, ignoreFiles, disclosures: [ignoreFiles.length ? `Plastic ignore policy applied (${ignoreFiles.length} file${ignoreFiles.length === 1 ? "" : "s"}).` : "Plastic workspace detected; no readable ignore.conf or cloaked.conf found."] });
+        if (ignoreFiles.length === 0) continue;
+        roots.push({ root: canonicalRoot, filterDecision: "applied", decisionCode: PLASTIC_IGNORE_FILES_APPLIED_CODE, filterBoundary: canonicalWorkspace, ignoreFiles, disclosures: [`Plastic ignore filter applied (${ignoreFiles.length} readable file${ignoreFiles.length === 1 ? "" : "s"}).`] });
       }
       return roots.length ? { outcome: "applied", roots } : { outcome: "not_applicable" };
     },