@cassiomc1/forgeloop 1.10.1 → 1.11.0

package/docs/RIPWIRE_ADAPTER.md

@@ -0,0 +1,189 @@
+# Ripwire advisory adapter
+
+This document explains the optional Ripwire integration shipped with
+ForgeLoop. It is an advisory context provider. It can help a host choose
+which source files to inspect, but it never controls ForgeLoop state, checks,
+receipts, commands, approvals, or completion.
+
+## When to use it
+
+Use the adapter when a host already has a qualified Ripwire executable and
+wants ranked source signatures for an explicit task query. Do not use it as a
+replacement for tests, code review, lifecycle evidence, or a sound call graph.
+Ripwire's resolver is approximate: same-file and same-directory edges are
+useful hints, while ambiguous or unresolved edges can be missing or wrong.
+
+ForgeLoop does not install Ripwire, search `PATH`, contact a server, create a
+cache, or persist a recall. The host owns executable selection and version
+qualification.
+
+## Registration
+
+Import the factory from the public integration entry point and register the
+returned provider under the exact `ripwire` key:
+
+```js
+import {
+  createForgeLoopContext,
+  createRipwireAdvisoryContextProvider,
+  recallAdvisoryContext,
+} from "@cassiomc1/forgeloop/integration";
+
+const ripwire = createRipwireAdvisoryContextProvider({
+  executablePath: "/absolute/path/to/ripwire",
+  expectedVersion: "0.3.8",
+});
+
+const runtimeContext = createForgeLoopContext({
+  advisoryContextProviders: { ripwire },
+});
+
+const context = await recallAdvisoryContext({
+  target: "/absolute/path/to/project",
+  taskId: "task-123",
+  providerName: "ripwire",
+  query: "stale handoff acceptance and repository fingerprint",
+  limit: 6,
+  runtimeContext,
+});
+```
+
+`executablePath` must be absolute. `expectedVersion` is an exact version token,
+not a range. Provider construction is inert. On every recall the adapter first
+runs `ripwire --version`; a mismatch fails with
+`E_ADVISORY_CONTEXT_PROVIDER_INVALID` before the query is attempted.
+
+## Process contract
+
+The adapter invokes one command with an argv array:
+
+```text
+<ripwire-path> <absolute-project-path> \
+  --for=<entire-query-string> --signatures-only --json --no-cache \
+  --exclude=.forgeloop
+```
+
+The query is one argument, so shell metacharacters cannot add arguments or
+commands. The child is started with `shell: false`, standard input is closed,
+and stdout/stderr are read concurrently. A single deadline covers the version
+probe and query. The default transport ceilings are 1 MiB for stdout and 64
+KiB for stderr. On timeout or overflow the child is terminated and the error
+uses a stable ForgeLoop code; raw output is not copied into the message.
+
+The `.forgeloop` exclusion keeps lifecycle files out of the advisory source
+surface. The adapter does not add other exclusion flags because every flag
+must be qualified against the selected Ripwire version.
+
+## JSON mapping
+
+Ripwire's `--for --json` response is expected to be an object containing a
+flat `sigs` array. Each known row is mapped as follows:
+
+| Ripwire field | ForgeLoop field | Rule |
+| --- | --- | --- |
+| `n` | `title` | Candidate symbol name. |
+| `sig` | `summary` | Signature text, bounded before core normalization. |
+| `p` + `l` | `sourceRef` | Repository-relative path and one-based line. |
+| `r`, `k` | summary annotation | Rank and ranking score remain descriptive text. |
+| numeric `confidence` in `[0, 1]` | `confidence` | Copied only when the upstream field is explicitly numeric and bounded. |
+| `at` | omitted | A run timestamp or revision is not needed for deterministic item identity. |
+
+PageRank, BM25, margin, and other ranking values are never converted into a
+probability. Unknown fields are discarded by the core allowlist. Candidate
+order is preserved, duplicates are removed by stable first occurrence, and
+items stop when the requested item or total-character budget is reached.
+
+The first item is always `Ripwire advisory status`. It states that the result
+is approximate and carries bounded disclosures such as `capped`, `sigs_total`,
+`sigs_shown`, `lens`, `ambiguous`, `unresolved`, `unindexed`, parse health, and
+`index_completeness=unknown`. If no symbol fits, the status item says so; an
+empty result never proves that the project has no impact.
+
+Source references are rejected when they are absolute outside the project,
+contain traversal segments, use an in-project symlink, or report an invalid
+line. The host must still inspect the referenced file and independently verify
+the proposed change.
+
+The status item is budget-aware. When candidates or diagnostic notices do not
+fit, it preserves a truthful completeness warning and says which candidate
+rows or text were omitted. The final item total is checked against the same
+character budget used by the core advisory normalizer.
+
+## Failure codes
+
+| Situation | Code |
+| --- | --- |
+| Missing or unqualified executable or unsafe target | `E_ADVISORY_CONTEXT_PROVIDER_UNAVAILABLE` |
+| Nonzero process exit without a qualified meaning | `E_ADVISORY_CONTEXT_RESULT_INVALID` |
+| Expected version differs from `--version` output | `E_ADVISORY_CONTEXT_PROVIDER_INVALID` |
+| Invalid JSON or unsupported response shape | `E_ADVISORY_CONTEXT_RESULT_INVALID` |
+| Timeout | `E_ADVISORY_CONTEXT_TIMEOUT` |
+| Stdout/stderr or candidate ceiling exceeded | `E_ADVISORY_CONTEXT_OUTPUT_LIMIT` |
+| Unsafe content or control character in selected context | `E_PORTABLE_CONTEXT_INVALID` |
+
+These failures affect the explicit recall operation only. They do not change a
+ForgeLoop task phase and do not write `.forgeloop` state.
+
+## Verification
+
+The deterministic fixture tests run without a Ripwire installation:
+
+```bash
+node --test \
+  tests/ripwire-advisory-process.test.js \
+  tests/ripwire-advisory-normalize.test.js \
+  tests/ripwire-advisory-provider.test.js
+```
+
+The real-binary smoke test is opt-in. Set both variables to a host-qualified
+binary and version, then run:
+
+```bash
+FORGELOOP_TEST_RIPWIRE_PATH=/absolute/path/to/ripwire \
+FORGELOOP_TEST_RIPWIRE_VERSION=0.3.8 \
+node --test tests/real-ripwire-advisory.test.js
+```
+
+Without those variables the test is skipped and interoperability remains
+`NOT_VERIFIED`. When it runs, it requires a candidate reference to the known
+fixture source and compares the complete fixture tree before and after recall,
+so a binary that mutates the project fails the test. The test does not install
+software or discover a binary.
+
+## Retrieval benchmark
+
+The retrieval benchmark is a repository-maintainer check. Its runner, cases,
+and fixture corpus are intentionally excluded from the core npm tarball; the
+published consumer surface is the adapter, its declarations, and this guide.
+Run it from a clean ForgeLoop checkout when a host-qualified Ripwire binary is
+available.
+
+`benchmarks/ripwire-context/cases.json` freezes six task-shaped queries,
+expected files, lexical baseline terms, and the ForgeLoop commit used for the
+comparison. Run the benchmark only against a clean checkout and an explicitly
+qualified binary:
+
+```bash
+node scripts/benchmark-ripwire-context.mjs \
+  --project /absolute/path/to/forgeloop \
+  --ripwire-path /absolute/path/to/ripwire \
+  --version 0.3.8 \
+  --cases benchmarks/ripwire-context/cases.json \
+  --runs 5 \
+  --json
+```
+
+The report includes per-case and per-run expected-file coverage, misses,
+irrelevant references, baseline bytes, normalized adapter bytes, transport
+bytes when observed, and median/min/max durations. A file seen in only one
+repetition is reported as observed across runs but does not count as a
+consistently found file. A missing binary, version, dirty checkout, or commit
+mismatch produces `NOT_VERIFIED`; it is never reported as a performance win.
+
+## Scope boundary
+
+The adapter is intentionally limited to source-map retrieval. It does not
+implement Ripwire's body packing, impact commands, cache management, server
+mode, automatic file reads, lifecycle transitions, evidence production, or
+publication. Those features require a separate contract and separate
+qualification work.

package/docs/TROUBLESHOOTING.md

@@ -33,6 +33,10 @@ This guide provides symptom-first recovery procedures for common ForgeLoop proto
 - [Structural-quality verification reports a regression](#symptom-structural-quality-verification-reports-a-regression)
 - [Structural-quality provider is unavailable or invalid](#symptom-structural-quality-provider-is-unavailable-or-invalid)
 - [Structural-quality evidence is stale or incomparable](#symptom-structural-quality-evidence-is-stale-or-incomparable)
+- [Repository Index is not ready](#symptom-repository-index-is-not-ready)
+- [Repository search fails](#symptom-repository-search-fails)
+- [Persistent search host is unavailable](#symptom-persistent-search-host-is-unavailable)
+- [Persistent search host ownership is unverified or stale](#symptom-persistent-search-host-ownership-is-unverified-or-stale)
 - [Another harness cannot resume the task](#symptom-another-harness-cannot-resume)
 - [Task claim conflict or recovered task](#symptom-task-creation-blocked-by-a-write-claim-conflict-e_task_scope_conflict)
 - [Stable Error & Reason Code Reference](#stable-error-and-reason-codes)
@@ -1016,6 +1020,120 @@ Resolve the legitimate drift through the normal task lifecycle. Do not edit a
 baseline or evaluation by hand, and do not use a bundle as a reason to bypass
 current-cycle validation.
 
+### Symptom: Repository Index is not ready
+
+#### What it means
+
+`forgeloop index-status` did not report `READY`. For a Git repository the
+engine is mandatory, so `doctor` and repository-wide search remain unhealthy
+until the pinned binary, derived index, and ForgeLoop-owned watcher are
+verified.
+
+#### Inspect
+
+```bash
+forgeloop index-status --json
+forgeloop doctor --json
+```
+
+#### Safe recovery
+
+1. Run `forgeloop index-start --json` when the index is complete but the
+   watcher is down.
+2. Run `forgeloop index-setup --asset /absolute/path/to/pinned-asset.tar.gz`
+   for a missing engine or an air-gapped host.
+3. Run `forgeloop index-rebuild --json` after corruption or a confirmed stale
+   index.
+
+Never delete the whole `.forgeloop` directory and never stop a process by
+executable name. A status of `DEFERRED` for a non-Git protocol fixture is
+intentional and is not evidence that a real repository is healthy.
+
+### Symptom: Repository search fails
+
+#### What it means
+
+The provider-neutral search service rejected the request, could not verify the
+managed engine, or received an invalid native result. Search never falls back
+silently to `rg`, `grep`, or an arbitrary `PATH` executable.
+
+#### Inspect
+
+```bash
+forgeloop search "pattern" --json
+forgeloop index-status --json
+```
+
+Correct request bounds such as the pattern, filters, context, or `max-count`
+when the error is `E_REPOSITORY_INDEX_REQUEST_INVALID`. For
+`E_REPOSITORY_INDEX_OUTPUT_INVALID`, preserve the bounded diagnostic and
+rebuild; repeated malformed output indicates a pinned-engine regression.
+Native exit code `1` means no matches and is normalized to a successful empty
+ForgeLoop result. Native exit code `2` is an actual search failure.
+
+### Symptom: Persistent search host is unavailable
+
+#### What it means
+
+The CLI-only local transport could not connect to or start its user-scoped
+ForgeLoop host within the bounded startup/request timeout. This is a transport
+failure, not permission to bypass the mandatory Repository Index or switch to
+`rg`, `grep`, or an arbitrary executable.
+
+#### Inspect
+
+```bash
+forgeloop doctor --json
+forgeloop index-status --json
+forgeloop search "pattern" --json
+```
+
+#### Safe recovery
+
+Retry the search once after confirming that the current package is complete
+and the managed Repository Index reports `READY`. The client performs at most
+one bounded transport recovery attempt. If it still fails, preserve the
+structured error and follow the Repository Index recovery procedure above;
+transport recovery does not rebuild task state or completion evidence.
+
+`E_PERSISTENT_TRANSPORT_UNAVAILABLE`,
+`E_PERSISTENT_TRANSPORT_TIMEOUT`, and
+`E_PERSISTENT_TRANSPORT_START_FAILED` identify the local transport boundary.
+The canonical search error, if one is returned after a successful connection,
+must be diagnosed as a Repository Index or request error instead.
+
+### Symptom: Persistent search host ownership is unverified or stale
+
+#### What it means
+
+The local state or endpoint does not prove that the live process is the expected
+ForgeLoop persistent host. Common causes include a host from another package
+version, a process that exited while state remained, endpoint substitution, or
+PID reuse. A PID or process name alone is never sufficient ownership evidence.
+
+#### Inspect
+
+```bash
+forgeloop doctor --json
+forgeloop search "pattern" --json
+```
+
+The sanitized `persistentTransport` status reports only its public schema,
+state, running/owned flags, and protocol/package versions. It intentionally
+does not print endpoint, home, lock, repository, index, binary, or entrypoint
+paths.
+
+#### Safe recovery
+
+Allow the CLI's bounded recovery path to reconcile a stale or incompatible
+transport state. Explicit shutdown also requires a verified endpoint and nonce.
+If the status remains `OWNERSHIP_UNVERIFIED`, do not kill a PID or delete a
+whole `.forgeloop` directory; inspect the structured error and use the normal
+package/process recovery boundary. The relevant stable codes are
+`E_PERSISTENT_TRANSPORT_OWNERSHIP_UNVERIFIED`,
+`E_PERSISTENT_TRANSPORT_HOST_STALE`, and
+`E_PERSISTENT_TRANSPORT_PROTOCOL_MISMATCH`.
+
 ## Stable Error and Reason Codes
 
 <!-- BEGIN FORGELOOP GENERATED: public-error-codes -->
@@ -1162,6 +1280,16 @@ current-cycle validation.
 | `E_NATIVE_ADAPTER_TARGET_MISSING` | A ForgeLoop protocol validation or lifecycle condition was not satisfied. | Inspect the structured command result, correct the named artifact or prerequisite, then run forgeloop next --json. |
 | `E_NEW_POLICY_VIOLATION` | New executable policy violation detected that is not present in brownfield baseline. | Fix the violation before completing the task. |
 | `E_OBSERVATION_INVALID` | A ForgeLoop protocol validation or lifecycle condition was not satisfied. | Inspect the structured command result, correct the named artifact or prerequisite, then run forgeloop next --json. |
+| `E_PERSISTENT_TRANSPORT_FRAME_INVALID` | The local persistent-search byte stream did not contain a complete valid JSON frame. | Retry the bounded local request; inspect the host only if malformed frames recur. |
+| `E_PERSISTENT_TRANSPORT_FRAME_TOO_LARGE` | A persistent-search request or response exceeded its bounded frame limit. | Narrow the search request or inspect the host resource boundary; oversized frames are rejected. |
+| `E_PERSISTENT_TRANSPORT_HOST_STALE` | Persistent-search state points to a host process that is no longer running. | Retry the CLI search so ForgeLoop can remove only the verified stale host state and restart it. |
+| `E_PERSISTENT_TRANSPORT_INVALID_REQUEST` | A local persistent-search request is outside the versioned transport contract. | Use the supported ForgeLoop search command or update the compatible client and host together. |
+| `E_PERSISTENT_TRANSPORT_INVALID_RESPONSE` | The persistent-search host returned a response outside the versioned transport contract. | Retry once through the bounded recovery path; do not consume an unvalidated response. |
+| `E_PERSISTENT_TRANSPORT_OWNERSHIP_UNVERIFIED` | ForgeLoop could not prove that the process or endpoint belongs to its user-scoped persistent-search host. | Do not terminate the process; inspect the endpoint and retry after resolving the ownership conflict. |
+| `E_PERSISTENT_TRANSPORT_PROTOCOL_MISMATCH` | The persistent-search client and host do not agree on the supported protocol version. | ForgeLoop may replace only a verified compatible host; otherwise update the installed package and retry. |
+| `E_PERSISTENT_TRANSPORT_START_FAILED` | The user-scoped persistent-search host could not start or become ready within its bounded startup window. | Inspect the structured diagnostics and retry; direct integration APIs remain available without this optimization. |
+| `E_PERSISTENT_TRANSPORT_TIMEOUT` | A persistent-search connection, handshake, or request exceeded its bounded timeout. | Retry once through the ownership-checked recovery path and inspect host/index health if it persists. |
+| `E_PERSISTENT_TRANSPORT_UNAVAILABLE` | The user-scoped persistent-search endpoint was not reachable. | ForgeLoop starts one verified local host and retries once; persistent failure is reported without an rg fallback. |
 | `E_PHASE_CHRONOLOGY_INVALID` | A ForgeLoop protocol validation or lifecycle condition was not satisfied. | Inspect the structured command result, correct the named artifact or prerequisite, then run forgeloop next --json. |
 | `E_PHASE_PREREQUISITE_MISSING` | A ForgeLoop protocol validation or lifecycle condition was not satisfied. | Inspect the structured command result, correct the named artifact or prerequisite, then run forgeloop next --json. |
 | `E_PHASE_TRANSITION_INVALID` | A ForgeLoop protocol validation or lifecycle condition was not satisfied. | Inspect the structured command result, correct the named artifact or prerequisite, then run forgeloop next --json. |
@@ -1208,6 +1336,25 @@ current-cycle validation.
 | `E_RECONCILE_REQUIREMENT_UNKNOWN` | The supplied check id and requirement text do not exactly match a contract verification item of type VERIFICATION. | Supply the exact id and requirement text of an existing contract verification item. |
 | `E_RECONCILE_UNSUPPORTED_DRIFT` | Work-state drift includes kinds other than REPOSITORY_CHANGED (contract or required-artifact drift). | Resolve contract or artifact drift through their dedicated recovery surfaces; reconcile-closure only refreshes repository fingerprint drift. |
 | `E_REPOSITORY_CHANGED` | The repository fingerprint (branch or HEAD) moved after the work-state checkpoint was recorded. | If the task objective is already satisfied in the current repository, run forgeloop reconcile-closure; otherwise resume from a checkpoint that matches the current repository. |
+| `E_REPOSITORY_INDEX_ENGINE_BINARY_CHECKSUM_MISMATCH` | The extracted or managed tgrep executable bytes do not match the pinned binary SHA-256 digest. | Run forgeloop index-setup or index-rebuild to repair the managed binary; do not run a mismatched executable. |
+| `E_REPOSITORY_INDEX_ENGINE_CHECKSUM_MISMATCH` | The tgrep archive or executable bytes do not match the pinned manifest SHA-256 digest. | Obtain the exact manifest asset and retry; do not install a checksum mismatch. |
+| `E_REPOSITORY_INDEX_ENGINE_DOWNLOAD_FAILED` | The pinned tgrep release asset could not be downloaded or read. | Retry with network access or preload the exact manifest archive; never bypass provisioning verification. |
+| `E_REPOSITORY_INDEX_ENGINE_EXECUTION_FAILED` | A managed tgrep process could not be launched, completed, or stayed within its execution boundary. | Inspect the structured error and index status, then retry with the verified managed engine. |
+| `E_REPOSITORY_INDEX_ENGINE_EXTRACTION_FAILED` | The tgrep archive is malformed, unsafe, or could not be extracted to a temporary directory. | Use the exact supported archive and retry; unsafe paths and links are rejected. |
+| `E_REPOSITORY_INDEX_ENGINE_MISSING` | The managed tgrep executable is absent, unreadable, or has not been provisioned. | Run forgeloop index-setup or preload the exact manifest archive with --asset. |
+| `E_REPOSITORY_INDEX_ENGINE_VERSION_MISMATCH` | The executable reports a version different from the ForgeLoop-pinned tgrep version. | Provision the manifest-pinned tgrep release and retry; do not use an unpinned binary. |
+| `E_REPOSITORY_INDEX_INDEXING` | The repository index is still being built or reconciled and is not ready for the requested operation. | Wait for index-status to report READY, or use index-rebuild if the operation remains stuck. |
+| `E_REPOSITORY_INDEX_LOCK_UNSAFE` | A Repository Index operation lock is malformed, conflicting, or cannot be safely acquired. | Wait for a concurrent operation to finish and retry; use status or rebuild for a persistent lock failure. |
+| `E_REPOSITORY_INDEX_NOT_INITIALIZED` | The repository index has no complete derived index available for the requested operation. | Run forgeloop index-setup or forgeloop index-rebuild for the selected repository. |
+| `E_REPOSITORY_INDEX_OUTPUT_INVALID` | Native tgrep output did not match the bounded provider-neutral JSON contract. | Treat the result as unusable, inspect the engine, and rebuild or provision the pinned release. |
+| `E_REPOSITORY_INDEX_OUTPUT_LIMIT` | Managed tgrep output exceeded ForgeLoop's bounded process-output limit. | Narrow the search or resource policy and retry; oversized output is never promoted to a result. |
+| `E_REPOSITORY_INDEX_PLATFORM_UNSUPPORTED` | The current operating-system and architecture pair has no pinned tgrep release asset. | Use a supported platform or add a separately reviewed manifest asset; do not substitute a PATH executable. |
+| `E_REPOSITORY_INDEX_REBUILD_FAILED` | The derived repository index could not be rebuilt successfully. | Inspect the structured failure, resource policy, and repository paths, then retry index-rebuild. |
+| `E_REPOSITORY_INDEX_REQUEST_INVALID` | Repository Index command input is outside the bounded provider-neutral request contract. | Correct the pattern, path filters, context, or lifecycle options and retry the canonical command. |
+| `E_REPOSITORY_INDEX_SEARCH_FAILED` | The native tgrep search failed with an execution or provider error; no-match is not an error. | Inspect index-status and retry the query or rebuild the derived index; ForgeLoop does not fall back silently. |
+| `E_REPOSITORY_INDEX_SERVER_START_FAILED` | The ForgeLoop-owned tgrep watcher could not be started or did not become healthy. | Run index-status, inspect the structured reason, and retry index-start or index-rebuild. |
+| `E_REPOSITORY_INDEX_SERVER_STOP_FAILED` | The ForgeLoop-owned tgrep watcher could not be stopped or its ownership could not be proven. | Use index-status and retry the canonical stop operation; never terminate processes by name or PID alone. |
+| `E_REPOSITORY_INDEX_SERVER_UNHEALTHY` | Repository Index server, metadata, process identity, or index readiness validation failed. | Run index-status, then use index-rebuild after resolving the reported boundary. |
 | `E_RESPONSIBILITY_FROZEN_INPUT_DRIFT` | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. | Inspect the structured command result, correct the named boundary or artifact, then retry the canonical command. |
 | `E_RESPONSIBILITY_INVALID` | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. | Inspect the structured command result, correct the named boundary or artifact, then retry the canonical command. |
 | `E_RESPONSIBILITY_REQUIRED_CHECK_MISSING` | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. | Inspect the structured command result, correct the named boundary or artifact, then retry the canonical command. |

package/docs/UNIVERSAL_INTEGRATION.md

@@ -67,6 +67,36 @@ may be absent only when the canonical protocol marks it not applicable;
 presentation depth cannot change evidence, verification truth, authority,
 provenance, safety-floor, or validator-backed completion requirements.
 
+### Repository Search boundary
+
+The Integration API exposes direct, transport-neutral repository operations:
+
+```js
+import {
+  repositorySearch,
+  repositoryIndexStatus,
+} from "@cassiomc1/forgeloop/integration";
+
+const result = await repositorySearch({
+  projectPath: ".",
+  pattern: "needle",
+  fixedStrings: true,
+});
+
+const status = await repositoryIndexStatus({ projectPath: "." });
+```
+
+These operations call the canonical Repository Search service and require the
+managed Repository Index for supported Git repositories. The shell-facing CLI
+`search` command may use the user-scoped persistent local IPC host described in
+[`PERSISTENT_SEARCH_TRANSPORT.md`](./PERSISTENT_SEARCH_TRANSPORT.md), but that
+host is only a CLI startup/reuse optimization. Integration API and MCP callers
+do not use it, and no transport carries lifecycle, claims, receipts, evidence,
+or completion authority.
+
+See [`REPOSITORY_INDEX.md`](./REPOSITORY_INDEX.md) for the normalized search
+contract, tgrep management, status resource, and maintenance commands.
+
 ### Usage and efficiency boundary
 
 Create a context with an optional trusted provider:

package/docs/diagrams/README.md

@@ -39,6 +39,15 @@ dark presentation so it remains legible in repository previews; the adjacent tex
 [`README.md`](../../README.md#architecture-flow) carries the same lifecycle
 semantics for text-only readers.
 
+Advisory context, including the optional Ripwire adapter, is intentionally not
+drawn as a lifecycle node or transition. It is a host-injected, explicit,
+non-evidence input that can guide inspection while remaining outside state,
+authority, verification, completion, and next-action decisions. Its boundary
+is documented in [`ADVISORY_CONTEXT.md`](../ADVISORY_CONTEXT.md) and
+[`RIPWIRE_ADAPTER.md`](../RIPWIRE_ADAPTER.md); keeping it out of these P0
+visuals prevents an optional side channel from being mistaken for protocol
+control flow.
+
 Archify is vendored at `vendor/archify/v2.15.0/archify` under its MIT license.
 The exact source commit and cryptographic vendor-tree hash are recorded in
 `vendor/archify/v2.15.0/PIN.json`; generated-file hashes are recorded in the
@@ -78,3 +87,13 @@ These explanations are part of the JSON sources and generated explorers;
 matching textual fallbacks live in the README, revision-provider guide, and
 attestation guide. Re-render before renewing a visual review, then inspect
 the new output at desktop and narrow widths before binding the review hashes.
+
+The Repository Index and Persistent Search Transport are runtime discovery
+boundaries rather than lifecycle transitions. Their current CLI/API/MCP
+separation and local IPC sequence are documented in
+[`REPOSITORY_INDEX.md`](../REPOSITORY_INDEX.md) and
+[`PERSISTENT_SEARCH_TRANSPORT.md`](../PERSISTENT_SEARCH_TRANSPORT.md). They are
+intentionally not added as a fourth Archify workflow merely to increase the
+diagram count; the README hero provides the conceptual architecture overview,
+while these three governed visuals remain focused on lifecycle, verification,
+and attestation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cassiomc1/forgeloop",
-  "version": "1.10.1",
+  "version": "1.11.0",
   "description": "Portable, verifiable engineering protocol for AI coding environments and developer workflows",
   "repository": {
     "type": "git",
@@ -24,6 +24,10 @@
     "schemas",
     "benchmarks/execution-profiles/*.json",
     "benchmarks/execution-profiles/README.md",
+    "benchmarks/repository-index/queries.json",
+    "benchmarks/repository-index/README.md",
+    "benchmarks/repository-index/run-hot-path.mjs",
+    "benchmarks/repository-index/run-persistent-transport.mjs",
     ".forgeloop/forgeloop.gitignore",
     "AGENTS.md",
     "CLAUDE.md",
@@ -52,6 +56,7 @@
     "docs/GETTING_STARTED.md",
     "docs/CROSS_HARNESS_CONTINUITY.md",
     "docs/ADVISORY_CONTEXT.md",
+    "docs/RIPWIRE_ADAPTER.md",
     "docs/CLI_REFERENCE.md",
     "docs/ARTIFACT_REFERENCE.md",
     "docs/TROUBLESHOOTING.md",
@@ -71,6 +76,8 @@
     "docs/PLATFORM_ADAPTERS.md",
     "docs/AGENT_PROTOCOL_SUMMARY.md",
     "docs/EXECUTION_PROFILE_BENCHMARKS.md",
+    "docs/REPOSITORY_INDEX.md",
+    "docs/PERSISTENT_SEARCH_TRANSPORT.md",
     "docs/KNOWLEDGE_SOURCES.md",
     "scripts/generate-shell-completions.mjs",
     "scripts/generate-agent-protocol-summary.mjs",
@@ -79,6 +86,8 @@
     "scripts/validate-execution-profile-benchmarks.mjs",
     "scripts/report-execution-profile-outliers.mjs",
     "scripts/report-tail-interpretation.mjs",
+    "scripts/verify-tgrep-manifest.mjs",
+    "scripts/update-tgrep-manifest.mjs",
     "scripts/check-efficiency-regression.mjs",
     "scripts/lib/execution-profile-benchmark-io.mjs",
     "scripts/benchmark-cli-startup.mjs",
@@ -130,7 +139,8 @@
     "benchmark:profiles:tail-analysis": "node scripts/report-tail-interpretation.mjs",
     "benchmark:profiles:regression": "node scripts/check-efficiency-regression.mjs",
     "transactions:compact": "node scripts/compact-transactions.mjs",
-    "complexity:check": "node scripts/check-complexity.mjs"
+    "complexity:check": "node scripts/check-complexity.mjs",
+    "repository-index:manifest": "node scripts/verify-tgrep-manifest.mjs"
   },
   "devDependencies": {
     "c8": "^12.0.0",

package/scripts/update-tgrep-manifest.mjs

@@ -0,0 +1,86 @@
+import { execFile as nodeExecFile } from "node:child_process";
+import { mkdtemp, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { validateTgrepManifest } from "../src/repository-index/manifest.js";
+import { sha256File, validateArchiveEntry } from "../src/repository-index/binary-manager.js";
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const manifestPath = path.join(packageRoot, "src", "repository-index", "tgrep-manifest.json");
+const args = process.argv.slice(2);
+const assetDirIndex = args.indexOf("--asset-dir");
+const assetDir = assetDirIndex >= 0 ? args[assetDirIndex + 1] : null;
+const shouldWrite = args.includes("--write");
+
+if (!assetDir || !path.isAbsolute(assetDir) || !shouldWrite) {
+  console.error("Usage: node scripts/update-tgrep-manifest.mjs --asset-dir /absolute/release-assets --write");
+  process.exit(1);
+}
+
+const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+validateTgrepManifest(manifest);
+
+function execFile(file, args, options = {}) {
+  return new Promise((resolve, reject) => {
+    nodeExecFile(file, args, { shell: false, ...options }, (error, stdout, stderr) => {
+      if (error) {
+        error.stdout = stdout;
+        error.stderr = stderr;
+        reject(error);
+        return;
+      }
+      resolve({ stdout, stderr });
+    });
+  });
+}
+
+async function listArchiveEntries(archivePath, archive) {
+  const command = archive === "zip" && process.platform !== "win32" ? "unzip" : "tar";
+  const args = command === "unzip" ? ["-Z1", archivePath] : ["-tf", archivePath];
+  const result = await execFile(command, args, { maxBuffer: 2 * 1024 * 1024 });
+  return result.stdout.split(/\r?\n/).filter(Boolean).map(validateArchiveEntry);
+}
+
+async function extractBinary(assetPath, asset, destination) {
+  const entries = await listArchiveEntries(assetPath, asset.archive);
+  if (!entries.some((entry) => path.posix.basename(entry) === asset.binaryName)) {
+    throw new Error(`archive does not contain ${asset.binaryName}`);
+  }
+  const command = asset.archive === "zip" && process.platform !== "win32" ? "unzip" : "tar";
+  const args = command === "unzip"
+    ? ["-q", assetPath, "-d", destination]
+    : ["-xf", assetPath, "-C", destination];
+  await execFile(command, args, { maxBuffer: 2 * 1024 * 1024 });
+
+  const found = [];
+  async function visit(directory) {
+    for (const entry of await readdir(directory, { withFileTypes: true })) {
+      const entryPath = path.join(directory, entry.name);
+      if (entry.isSymbolicLink()) throw new Error(`archive extracted a symbolic link: ${entry.name}`);
+      if (entry.isDirectory()) await visit(entryPath);
+      else if (entry.isFile() && entry.name === asset.binaryName) found.push(entryPath);
+    }
+  }
+  await visit(destination);
+  if (found.length !== 1) throw new Error(`expected exactly one ${asset.binaryName}, found ${found.length}`);
+  return found[0];
+}
+
+for (const asset of Object.values(manifest.assets)) {
+  const assetPath = path.join(assetDir, asset.assetName);
+  const info = await stat(assetPath);
+  if (!info.isFile()) throw new Error(`asset is not a regular file: ${assetPath}`);
+  asset.sha256 = await sha256File(assetPath);
+  const extractionDirectory = await mkdtemp(path.join(os.tmpdir(), "forgeloop-tgrep-manifest-"));
+  try {
+    const extractedBinary = await extractBinary(assetPath, asset, extractionDirectory);
+    asset.binarySha256 = await sha256File(extractedBinary);
+  } finally {
+    await rm(extractionDirectory, { recursive: true, force: true });
+  }
+}
+validateTgrepManifest(manifest);
+await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+console.log(`updated ${manifestPath}`);

package/scripts/verify-tgrep-manifest.mjs

@@ -0,0 +1,17 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { validateTgrepManifest } from "../src/repository-index/manifest.js";
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const manifestPath = path.join(packageRoot, "src", "repository-index", "tgrep-manifest.json");
+
+try {
+  const value = JSON.parse(await readFile(manifestPath, "utf8"));
+  validateTgrepManifest(value);
+  console.log(`valid tgrep manifest: ${value.engine} ${value.version} (${Object.keys(value.assets).length} assets)`);
+} catch (error) {
+  console.error(`invalid tgrep manifest: ${error.message}`);
+  process.exitCode = 1;
+}