V48 Gate 3 (specification-implementation): file-tree pickers for source path hints + protected IP exclusions

Source path hints and Protected IP exclusions on /deposits are no
longer typed — they are picked from the repository FILE TREE fetched at
the selected repository·branch·commit:

- New VCS `tree` resource (`/api/vcs?resource=tree&owner&repo&path&ref`)
  backed by VCSService.getRepositoryContent (provider listFiles), with
  empty/mock payloads alongside the existing resources.
- New VCSFileTreePicker: lazy per-directory loading, expand/collapse,
  file rows select their exact path, directory rows select their prefix
  (`dir/`), selected-path chips with × removal, square theme.
- MUTUAL EXCLUSIVITY: each picker receives the other's selections as
  conflicting paths — conflicting rows are disabled and labeled
  ('Already a source path hint' / 'Already a protected IP exclusion').
- Page state becomes string arrays; the dispatch payload sends
  protectedIpExclusions as an array (route already accepts arrays or
  newline strings); concept-level withholding is directed to the
  Obfuscations field (caption + explainer copy updated).

Tests: new vcsFileTreePicker suite (empty state, ref-scoped fetch, lazy
directory loading, file/prefix selection, chip removal, conflict
disabling); the deposit dispatch-with-exclusions test now picks
'secret-engine/' from the tree and asserts the array payload.

Spec: presentation-laws section gains the path-inputs-are-file-tree-
pickers law (fetched at the selected source package, mutually
exclusive, arrays on the wire, concepts → Obfuscations).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: geraldarthurdavis

BITCODE_SPEC_V48_NOTES.md

@@ -611,8 +611,17 @@ shared transactions/telemetry components) is governed by these laws:
   TERMINAL_REPOSITORY_PROVIDERS with live connection state as the item
   description; switching provider rewrites the provider param and clears
   repo/branch/commit).
-- **Examples are placeholders.** Form fields never prefill example values —
-  source path hints ships empty with the examples as placeholder text.
+- **Examples are placeholders.** Form fields never prefill example values.
+- **Path inputs are file-tree pickers.** Source path hints and Protected IP
+  exclusions are picked from the repository FILE TREE fetched at the
+  selected repository·branch·commit (new VCS `tree` resource →
+  `VCSService.getRepositoryContent`, lazy per-directory), never typed:
+  a file selects its exact path, a directory selects its prefix (`dir/`).
+  The two selections are MUTUALLY EXCLUSIVE — a path picked on one side is
+  disabled on the other, labeled with why. The dispatch payload carries the
+  exclusions as an array (the route accepts arrays or newline strings).
+  Concept-level withholding belongs to the Obfuscations field, not the
+  exclusion picker.
 - **Aside cards are non-collapsible.** The Earnings / Governance / Session
   cards are plain sections; only their inner disclosures (Opportunity
   roots, Authority blockers, Disclosure boundary, Deposit proof detail)

uapi/app/api/vcs/route.ts

@@ -18,6 +18,7 @@ const resourceSchema = z.enum([
   'branches',
   'commits',
   'issues',
+  'tree',
 ]);
 const providerSchema = z.enum(['github', 'gitlab', 'bitbucket']);
 
@@ -51,6 +52,8 @@ function buildEmptyResourcePayload(resource: z.infer<typeof resourceSchema>) {
       return { commits: [] };
     case 'issues':
       return { issues: [] };
+    case 'tree':
+      return { items: [] };
   }
 }
 
@@ -133,6 +136,13 @@ function buildMockPayload(resource: z.infer<typeof resourceSchema>, provider: VC
           },
         ],
       };
+    case 'tree':
+      return {
+        items: [
+          { path: 'src', type: 'tree', sha: 'mock-tree-src' },
+          { path: 'README.md', type: 'blob', sha: 'mock-blob-readme', size: 2048 },
+        ],
+      };
   }
 }
 
@@ -236,6 +246,19 @@ export async function GET(request: Request) {
         const commits = await vcsService.listCommits(connectionHandle, owner, repo, { branch });
         return NextResponse.json({ commits });
       }
+      case 'tree': {
+        if (!owner || !repo) return NextResponse.json(buildEmptyResourcePayload(resource));
+        const treePath = url.searchParams.get('path') || '';
+        const ref = url.searchParams.get('ref') || undefined;
+        const items = await vcsService.getRepositoryContent(
+          connectionHandle,
+          owner,
+          repo,
+          treePath,
+          ref,
+        );
+        return NextResponse.json({ items });
+      }
       case 'issues': {
         if (!owner || !repo) return NextResponse.json(buildEmptyResourcePayload(resource));
         const [issues, pullRequests] = await Promise.all([

uapi/app/deposits/DepositPageClient.tsx

@@ -81,6 +81,7 @@ import {
   DEPOSIT_SESSION_ROW_EXPLAINERS,
 } from "@/app/deposits/deposit-stat-explainers";
 import { TelemetryExplainerTrigger } from "@/components/base/bitcode/execution/TelemetryExplainerTrigger";
+import { VCSFileTreePicker } from "@/components/base/bitcode/vcs/VCSFileTreePicker";
 import type {
   DepositOptionReviewDecision,
   DepositOptionReviewDecisionState,
@@ -157,8 +158,10 @@ export default function DepositPageClient() {
   const [obfuscations, setObfuscations] = useState(
     "Note anything to obfuscate or withhold from the synthesized options: internal names, proprietary framing, or sensitive specifics the source-safe AssetPacks should avoid surfacing.",
   );
-  const [sourcePathHintsText, setSourcePathHintsText] = useState("");
-  const [protectedIpExclusionsText, setProtectedIpExclusionsText] = useState("");
+  // Picked from the repository file tree (selected repo·branch·commit);
+  // hints and exclusions are mutually exclusive path sets.
+  const [sourcePathHints, setSourcePathHints] = useState<string[]>([]);
+  const [protectedIpExclusions, setProtectedIpExclusions] = useState<string[]>([]);
   const [optionsRequested, setOptionsRequested] = useState(false);
   const [synthesisRunId, setSynthesisRunId] = useState<string | null>(null);
   // Whether the attached run is an option synthesis (its completed output
@@ -386,14 +389,6 @@ export default function DepositPageClient() {
     ],
   );
 
-  const sourcePathHints = useMemo(
-    () =>
-      sourcePathHintsText
-        .split(/\r?\n|,/u)
-        .map((entry) => entry.trim())
-        .filter(Boolean),
-    [sourcePathHintsText],
-  );
   const sourceCriticalitySignals = useMemo(
     () => [
       {
@@ -943,7 +938,7 @@ export default function DepositPageClient() {
           sourceBranch: repositoryContext?.selectedBranch || null,
           sourceCommit: repositoryContext?.selectedCommit || null,
           obfuscations: effectiveInstructions,
-          protectedIpExclusions: protectedIpExclusionsText,
+          protectedIpExclusions,
           demandContext: [
             ...depositRouteInput.depositoryDemandSignals.map(
               (signal) => signal.label,
@@ -989,7 +984,7 @@ export default function DepositPageClient() {
     depositRouteInput.depositoryDemandSignals,
     depositRouteInput.existingDepositorySignals,
     depositRouteInput.readingDemandSignals,
-    protectedIpExclusionsText,
+    protectedIpExclusions,
     refreshLiveRuns,
     replaceDepositRouteTransaction,
     repositoryContext,
@@ -1515,7 +1510,7 @@ export default function DepositPageClient() {
                       sourceBranch: repositoryContext?.selectedBranch ?? null,
                       sourceCommit: repositoryContext?.selectedCommit ?? null,
                       obfuscations,
-                      protectedIpExclusions: protectedIpExclusionsText,
+                      protectedIpExclusions,
                     },
                     outputDetails: synthesisActivity.outputDetails,
                     events: synthesisEvents,
@@ -1578,47 +1573,68 @@ export default function DepositPageClient() {
                     className="mt-2 min-h-[8rem] w-full border border-white/10 bg-black/30 px-3 py-3 text-sm leading-6 text-neutral-100 outline-none transition focus:border-emerald-300/35"
                   />
                 </div>
+                {/* File-tree pickers over the selected repository·branch·
+                    commit. Hints and exclusions are MUTUALLY EXCLUSIVE — a
+                    path picked on one side is disabled on the other.
+                    Concept-level withholding belongs to Obfuscations above. */}
                 <div className="mt-4 grid gap-4 tablet:grid-cols-2">
                 <div className="block">
                   <span className="flex items-center gap-2 text-[0.62rem] uppercase tracking-[0.16em] text-neutral-500">
-                    <label htmlFor="deposit-source-path-hints-input">Source path hints</label>
+                    <span>Source path hints</span>
                     <span onClick={(event) => event.stopPropagation()}>
                       <BitcodeInlineExplainer explainer={DEPOSIT_SECTION_EXPLAINERS.sourcePathHints} triggerAriaLabel="More info about this field" />
                     </span>
                   </span>
-                  <textarea
-                    id="deposit-source-path-hints-input"
-                    value={sourcePathHintsText}
-                    onChange={(event) =>
-                      setSourcePathHintsText(event.target.value)
-                    }
-                    placeholder={"e.g. uapi/app/terminal/TerminalDepositComposer.tsx\npackages/pipelines/asset-pack/src/depository-supply-index.ts"}
-                    className="mt-2 min-h-[6rem] w-full border border-white/10 bg-black/30 px-3 py-3 font-mono text-xs leading-5 text-neutral-100 outline-none transition focus:border-emerald-300/35"
-                  />
+                  <div className="mt-2">
+                    <VCSFileTreePicker
+                      aria-label="Source path hints file tree"
+                      provider={repositoryContext?.provider ?? "github"}
+                      repositoryFullName={
+                        repositoryContext?.selectedRepository?.fullName ?? null
+                      }
+                      treeRef={
+                        repositoryContext?.selectedCommit ||
+                        repositoryContext?.selectedBranch ||
+                        null
+                      }
+                      selectedPaths={sourcePathHints}
+                      onChange={setSourcePathHints}
+                      conflictingPaths={protectedIpExclusions}
+                      conflictLabel="Already a protected IP exclusion"
+                    />
+                  </div>
                 </div>
                 <div className="block">
                   <span className="flex items-center gap-2 text-[0.62rem] uppercase tracking-[0.16em] text-neutral-500">
-                    <label htmlFor="deposit-protected-ip-exclusions-input">
-                      Protected IP exclusions (one per line)
-                    </label>
+                    <span>Protected IP exclusions</span>
                     <span onClick={(event) => event.stopPropagation()}>
                       <BitcodeInlineExplainer explainer={DEPOSIT_SECTION_EXPLAINERS.protectedIpExclusions} triggerAriaLabel="More info about this field" />
                     </span>
                   </span>
-                  <textarea
-                    id="deposit-protected-ip-exclusions-input"
-                    value={protectedIpExclusionsText}
-                    onChange={(event) =>
-                      setProtectedIpExclusionsText(event.target.value)
-                    }
-                    placeholder={"e.g. src/secret-engine/\ninternal pricing model"}
-                    className="mt-2 min-h-[6rem] w-full border border-amber-300/15 bg-black/30 px-3 py-3 font-mono text-xs leading-5 text-neutral-100 outline-none transition focus:border-amber-300/40"
-                  />
+                  <div className="mt-2">
+                    <VCSFileTreePicker
+                      aria-label="Protected IP exclusions file tree"
+                      provider={repositoryContext?.provider ?? "github"}
+                      repositoryFullName={
+                        repositoryContext?.selectedRepository?.fullName ?? null
+                      }
+                      treeRef={
+                        repositoryContext?.selectedCommit ||
+                        repositoryContext?.selectedBranch ||
+                        null
+                      }
+                      selectedPaths={protectedIpExclusions}
+                      onChange={setProtectedIpExclusions}
+                      conflictingPaths={sourcePathHints}
+                      conflictLabel="Already a source path hint"
+                    />
+                  </div>
                   <span className="mt-1 block text-xs leading-5 text-neutral-500">
-                    Excluded paths and concepts never enter AssetPack knowledge
-                    synthesis: they are removed from the source inventory before
+                    Excluded paths never enter AssetPack knowledge synthesis:
+                    they are removed from the source inventory before
                     measurement, and candidates that touch them are dropped
-                    fail-closed.
+                    fail-closed. Concept-level withholding belongs in
+                    Obfuscations above.
                   </span>
                 </div>
                 </div>

uapi/app/deposits/deposit-explainers.ts

@@ -129,7 +129,7 @@ export const DEPOSIT_SECTION_EXPLAINERS = {
     kicker: 'Option synthesis',
     title: 'Source path hints',
     summary:
-      'Optional pointers (one per line or comma-separated) to paths or concepts worth flagging — used to estimate this deposit\'s criticality and cost, not to change what synthesis measures.',
+      'Optional pointers picked from the repository file tree (at the selected branch and commit) to paths worth flagging — used to estimate this deposit\'s criticality and cost, not to change what synthesis measures.',
     detail:
       'Hints that look sensitive (mentioning secrets, credentials, wallets, auth, keys, payments, or settlement) raise a review warning and nudge the deposit\'s estimated development cost and expected settlement upward — a client-side heuristic, not a synthesis-time exclusion.',
     points: [
@@ -140,7 +140,7 @@ export const DEPOSIT_SECTION_EXPLAINERS = {
   }),
   protectedIpExclusions: buildExplainer({
     kicker: 'Option synthesis',
-    title: 'Protected IP exclusions (one per line)',
+    title: 'Protected IP exclusions',
     summary:
       'The hard, fail-closed boundary: paths and concepts listed here never enter AssetPack knowledge synthesis at all.',
     detail: