@functional-systems/srcx 0.1.0-dev.1 → 0.1.0-dev.10

package/CHANGELOG.md

@@ -2,6 +2,59 @@
 
 ## Unreleased
 
+- Retain allowlisted CLI evaluation failure diagnostics without raw output or credentials.
+- Prepare an offline, unreviewed Click/Cobra question set with pinned source evidence.
+- Default CLI search/read evaluation across two pinned public repositories, with
+  alternative answer sets, exact source verification, and complete stdout accounting.
+- Internal reproducible lexical chunking evaluation with pinned source labels,
+  equal path-only enrichment, isolated live indexes, and token-budget metrics.
+
+### Added
+
+- Opt-in managed `text-embedding-3-large` (3072 dimensions) in separate pinned
+  Collections, with paired small/large evaluation and unchanged small identities.
+
+- Paired identifier/natural-language/mixed-query diagnostics on eight new tasks,
+  with verified candidate-rank coverage and offline stdout-budget analysis.
+- Bounded actual-CLI lexical/semantic/hybrid evaluation on identical managed
+  corpora, with reviewed and original labels, per-question regressions, stdout
+  token counts, command timings and durable request reservations.
+
+- Opt-in LambdaDB managed OpenAI `text-embedding-3-small` Collections, offline
+  embedding input previews, and explicit semantic/RRF hybrid search modes.
+- Candidate validation of generated vectors separately from exact source payloads,
+  unchanged-record reuse, and a bounded synthetic managed acceptance harness.
+
+- Persistent one-to-one Git branch / Collection Branch mapping, branch-local
+  incremental updates, and branch-selected search, resolve, and read against the
+  last published commit Tag.
+- Remote pending import ownership and resumable in-place branch updates, including
+  shared commit Tags across branches and non-fast-forward Git branch changes.
+- `test:live:branches` for repeatable synthetic live acceptance with retained
+  checkpoint, retry, and resource evidence.
+
+### Changed
+
+- Git branch imports update their fixed `git-*` writer; SHA/tag imports retain
+  manual workspaces. Existing publications and pending manual journals remain
+  usable. See README for migration and artifact behavior.
+- Ambiguous indexed branch/Git tag names require explicit `refs/heads/...` or
+  `refs/tags/...` selectors.
+
+### Fixed
+
+- Fetch omitted managed vectors from query responses through the same immutable
+  Tag, preserving hit order/scores and requiring exact non-vector payload equality.
+
+- Reject an unprepared CLI evaluation run before creating its root/lock so a
+  subsequent offline preparation can use the same path.
+- Pin branch control before enumerating versions so a concurrent publication
+  cannot advance the selector beyond the version list being read.
+- Reject live checkpoint reuse across different code/harness inputs and preserve
+  the original validation revision and completion time on same-input reruns.
+
+## [0.1.0-dev.1] - 2026-09-25
+
 ### Added
 
 - Git commit imports, syntax-aware chunks, immutable LambdaDB versions, lexical
@@ -17,4 +70,6 @@
 - Pending imports resume without the previous local build artifact.
 - Search/read `--version` selects the corpus instead of printing the CLI version.
 
-No npm release has been published yet.
+Initial npm bootstrap published to the `dev` channel from commit
+`f94f947bf593b2f8498c07e130933b0ab444f868`. This local bootstrap has no
+GitHub Actions provenance. No stable release has been published.

package/DESIGN.md

@@ -18,14 +18,13 @@ supporting each result. The project name is `srcx`.
 | --- | --- |
 | Project and display name | `srcx` |
 | Local directory | `srcx` |
-| Intended GitHub repository | `lambdadb/srcx` |
+| GitHub repository | `lambdadb/srcx` |
 | CLI executable | `srcx` |
-| Intended npm package | `@functional-systems/srcx` |
+| npm package | `@functional-systems/srcx` |
 | Short description | Version-aware code search on LambdaDB |
 
-The name is selected; the GitHub repository and npm package have not been created
-or published in this project. The package manifest and executable entry point are
-present in the initial CLI. Keep display/configuration naming centralized and
+The public GitHub repository and npm development channel are available. Current
+publication evidence and stable-release status are recorded in RELEASING.md. Keep display/configuration naming centralized and
 distribution identity in `package.json`. Database IDs and the existing
 `code-*` Collection naming and `purpose=code-search-v1` protocol marker remain
 independent of the product name.
@@ -40,7 +39,7 @@ Confirmed boundaries from the discussion:
 - Map each Git tag to a LambdaDB Alias targeting its published commit Tag.
   Multiple Git tags for the same commit share one commit Tag and Snapshot.
 - Keep search results and subsequent source reads pinned to the selected version.
-- Replace a changed file's entire chunk set initially; cache embeddings by input.
+- Replace a changed file's entire chunk set initially; retain unchanged remote records.
 - Keep core LambdaDB work, GitHub App/webhooks, UI, MCP, and a public SaaS outside
   the first deliverable. sbrain reference documents remain unchanged.
 - No remote repository creation, application commit, push, publication, real
@@ -72,9 +71,10 @@ This document is not a deployed-revision audit or evidence of a passing live run
 
 The initial command set below is implemented; run it as `node dist/cli.js` from
 this checkout after `npm run build`. See README for exact options and recovery.
-The first implementation uses fresh `work-*` Branches and observed-local-tag Alias
-synchronization; persistent tracked branches and authoritative pruning remain
-follow-up work. Immutable manifest `requestedRef` is normalized to the resolved
+Git branch imports now reuse persistent `git-*` Branches; explicit commit/tag
+imports use frozen `work-*` writers. Observed-local-tag Alias synchronization is
+implemented; automatic Git observation and authoritative pruning remain follow-up
+work. Immutable manifest `requestedRef` is normalized to the resolved
 commit OID; the
 original user spelling remains in the local build artifact. The broader contract
 below remains the target design.
@@ -379,9 +379,10 @@ readers on multiple machines do not require local registration state.
    changed/deleted file, compute obsolete IDs as previous file/chunk IDs minus
    replacement IDs. A deleted file has an empty replacement set. Obtain previous
    IDs from the inventory, not mutable query-by-path results.
-6. Apply the pinned per-chunk embedding policy. If embeddings are enabled, batch
-   eligible cache misses across chunks/files within the provider's token/request
-   limits. Validate successful vectors before caching.
+6. Apply the pinned per-chunk embedding policy. The managed preset materializes
+   eligible `embeddingText` inputs without calling a provider locally. LambdaDB
+   generates vectors during ordinary upsert. Skip unchanged remote records and
+   validate generated vectors in the candidate Tag before publication.
    Bound queue memory; do not load an entire repository's content into RAM.
 7. Materialize deterministic records and deletion lists as local build artifacts.
    Produce size-bounded inventory parts and a root manifest template. Check all
@@ -389,8 +390,10 @@ readers on multiple machines do not require local registration state.
    journal supplies the separate attempt ID when sealing the final manifest.
 
 Dry-run executes the same inventory/chunking path but performs no database mutation
-or embedding call. For pending embedding misses, report tokens and projected vector
-size separately; do not claim a completed vector/records hash. Report every entry,
+or embedding call. Report `managed` eligible chunks and `managedTokens` (estimated
+input tokens for the complete corpus), with `embedded=0` in the local artifact.
+These are not billed usage or incremental upload counts. Record hashes bind the
+submitted payload; server-generated vectors are validated separately. Report every entry,
 exclusion reason, parse status, byte size, chunk/token counts, embedding eligibility
 and skip reasons, and change summary. Dry-run plans may show pending embedding work;
 published chunk records may not silently treat missing required vectors as skips.
@@ -473,11 +476,12 @@ fields are omitted when absent; records of different kinds need not share them.
 | Record | Additional stored fields |
 | --- | --- |
 | File (`kind=file`) | `path`, `blobOid`, `contentHash`, `byteLength`, `sourceText`, `language`, `parseStatus`, `chunkCount` |
-| Chunk (`kind=chunk`) | `fileId`, `path`, parent `contentHash`, `language`, `chunkKind`, `startByte`, `endByte`, `startLine`, `endLine`, `ordinal`, `searchText`, `embeddingStatus`; optional `symbol`, `scope`, `signature`, `embeddingSkipReason`, `embeddingInputHash`, `embedding` |
+| Chunk (`kind=chunk`) | `fileId`, `path`, parent `contentHash`, `language`, `chunkKind`, `startByte`, `endByte`, `startLine`, `endLine`, `ordinal`, `searchText`, `embeddingStatus`; optional `symbol`, `scope`, `signature`, `embeddingSkipReason`, `embeddingInputHash`, `embeddingText`, `embedding` |
 | Corpus root (`kind=manifest`, `role=corpus`, ID `__manifest__`) | `repoId`, `indexId`, full `commitOid`, `commitTime`, `requestedRef`, full `config`, `inventoryHash`, `recordsHash`, `counts`, `buildId`, `attemptId`, `inventoryPartIds` |
 | Inventory part (`kind=manifest`, `role=inventory`) | `partOrdinal`, `partHash`, ordered `entries` with path, file/chunk IDs, blob/content identities, inclusion/exclusion reasons, parse states, sizes, and embedding coverage |
 | Repository control (`kind=manifest`, `role=repository`, main ID `__repo__`) | Full source identity, repo/index IDs, immutable preset/config, initialization state |
-| Ref control (`kind=manifest`, `role=git-ref`, main) | Full Git ref name, encoded Alias/Branch name, observed commit/time, applied version and synchronization state |
+| Git tag control (`kind=manifest`, `role=git-ref`, main) | Full Git tag ref, encoded Alias name, observed commit, applied version and synchronization state |
+| Git branch control (`kind=manifest`, `role=git-branch`, main) | Full Git branch ref, encoded Branch name, validated writer baseline, canonical published Tag and pending attempt identity |
 | Validation summary (`kind=manifest`, `role=validation`, main) | Candidate name/Snapshot, build/config/attempt identity, verifier version and checked counts/hashes; no premature claim of publication |
 
 `startByte`/`endByte` are half-open; display lines are one-based/inclusive.
@@ -486,8 +490,13 @@ content such as function, declaration, documentation, imports, or fallback; it i
 separate from the file/chunk/manifest discriminator. `counts` includes included and
 excluded files, chunks, and embedded/skipped chunks with reason totals.
 
-In a completed corpus, `embeddingStatus=embedded` requires a valid vector and
-`embeddingInputHash`, and omits the skip reason. `embeddingStatus=skipped` requires
+The managed preset uses `embeddingStatus=managed` to identify its generation policy,
+not local completion. Eligible chunks carry `embeddingText=searchText` and an
+`embeddingInputHash` over the exact input and embedding configuration; ordinary
+upserts omit `embedding`. A completed candidate must contain a nonzero, finite
+1536-number vector for every eligible chunk. Local artifacts contain no vectors.
+The internal fixture-only client embedder retains `embeddingStatus=embedded`;
+its arbitrary presets cannot be published through the CLI. `embeddingStatus=skipped` requires
 an explicit policy reason and omits the vector and input hash. The lexical-only
 preset records `embedding-disabled`; an embedding-enabled preset records its
 specific exclusion reason. Pending or failed required embedding work stays in the
@@ -548,10 +557,13 @@ baseline, not a proven code-specific ranking solution. An initial enrichment
 candidate preserves original identifiers while adding camelCase/snake_case terms;
 pin and evaluate that transformation before adopting it as the preset.
 
-An embedding-enabled preset adds an unmanaged `embedding` vector field with a
-concrete model-selected dimension and similarity metric, fixed before Collection
-creation. An indexed vector field does not require a vector on every chunk; file
-and manifest records also omit it. The `none` preset omits the vector index entirely.
+The opt-in managed preset adds indexed text `embeddingText` and a managed
+`embedding` vector field with provider `openai`, model `text-embedding-3-small`,
+1536 dimensions and cosine similarity. The source field, dimensions and similarity
+are nested under the vector field's `embedding` configuration; there are no
+top-level dimension/similarity properties. Collection discovery verifies the
+complete resolved schema and pinned preset. Missing `embeddingText` on skipped
+chunks, files and manifests means no vector is generated for those records. The `none` preset omits the vector index entirely.
 Changing presets creates a separate index; do not silently mutate an existing
 serving index. Do not write placeholder or test vectors into a real corpus.
 
@@ -740,13 +752,36 @@ choice and the finer skip rules remain evaluation decisions, not measured result
 
 ### Embedding reuse
 
-Cache embeddings by the exact full input and provider/model/revision/dimensions/
-preprocessing settings. Do not include commit, line numbers, file IDs, or build IDs
-in that input. A line shift can update positions while reusing the same vector;
-changed chunk boundaries or a renamed path in the input can legitimately miss.
-Cache only successful validated outputs atomically. Query embeddings use the same
-compatible contract and have their own cache/budget accounting. Provider aliases
-may drift if no immutable model revision exists; record that limitation.
+The managed implementation reuses unchanged records from the immutable baseline:
+compare all submitted payload fields after separately validating and removing only
+the server-generated vector. Do not upload those unchanged records again. Direct
+managed vector writes are forbidden, including copies fetched from an old Tag.
+Changed files receive new chunk IDs and may require re-embedding even if some text
+is identical. Replaying an uncertain write may also incur embedding usage. There
+is no srcx-managed document or query vector cache and no promised server cache.
+The older local cache remains only for internal client-embedder fixtures.
+
+The input includes path/symbol context and source text, not commit/line/build IDs.
+The preset pins provider/model/dimensions/similarity and input policy, but the
+provider model name is not an immutable model revision. Validation proves vector
+shape and payload integrity, not deterministic numerical reproduction by OpenAI.
+
+Search remains lexical by default. Explicit `--mode semantic` uses managed
+`knn.queryText`; `--mode hybrid` combines the existing lexical query and that kNN
+query using LambdaDB RRF. Both legs enforce `kind=chunk` and the same optional
+path/language filters; kNN uses a prefilter and `k=limit`. The lexical leg keeps
+nonembedded chunks eligible. Query/fetch/list request vectors explicitly so the
+same validation applies to pinned result handles. When a deployment omits managed
+vectors from list responses, fetch the affected IDs from that same immutable Tag
+and require identical non-vector payloads before vector validation. Source reads still use the
+original file bytes, never enriched text. No relevance gain is claimed yet.
+
+Managed source text and semantic/hybrid query text are sent through LambdaDB to
+OpenAI and incur embedding usage plus normal LambdaDB operations/storage. Dry-run
+and lexical queries do not request query embeddings. Use explicit opt-in and a
+bounded synthetic acceptance run before evaluating private or larger corpora.
+See [managed embeddings](https://docs.lambdadb.ai/guides/collections/managed-embeddings)
+and [hybrid query](https://docs.lambdadb.ai/guides/search/hybrid) for the API contract.
 
 ## 9. Candidate validation, publication, and `versions`
 
@@ -814,10 +849,16 @@ they do not authorize the next commit on that workspace.
    attempt identity and verifier version. Use an ID derived from the full commit
    OID and candidate Snapshot ID so attempts cannot overwrite another Snapshot's
    evidence. Confirm its readback before publication.
-5. Create the deterministic published Tag **from the validated candidate Tag**,
-   not from the mutable Branch. Verify both Tags have the same Snapshot ID and
-   matching manifest. Publication changes naming, not corpus content.
-6. Update optional branch-progress/control records and return the published version.
+5. For a first publication, create the deterministic published Tag **from the
+   validated candidate Tag**, not from the mutable Branch. Verify both Tags have
+   the same Snapshot ID and matching manifest. If the commit is already published,
+   validate and reuse its canonical Tag; retain this writer's validated candidate
+   separately when its Snapshot ID differs. Publication never overwrites a commit
+   Tag with another writer's snapshot.
+6. For a tracked Git branch, update its control record with the validated writer
+   snapshot and published commit Tag, clear pending ownership, and return the
+   published version. Branch selectors keep using the preceding published Tag
+   until this control update succeeds.
    A delayed bookkeeping write does not erase an already published immutable Tag.
 
 An empty Snapshot or incomplete candidate never becomes published. A stale Tag
@@ -827,6 +868,33 @@ avoid repeatedly validating known stale Snapshot IDs. A payload/build defect
 requires explicit same-build recovery, not endless polling. Publication must
 finish before the same code Branch starts a later commit.
 
+### Persistent Git branch state
+
+Each full `refs/heads/...` name maps to one `git-<ref-digest>` writer and one
+`branch-<full-ref-digest>` control document on main (`role=git-branch`). The control
+record holds the last applied immutable baseline, canonical published Tag name,
+and pending attempt/build/commit identity. Record pending ownership before branch
+creation or corpus writes. A missing local journal cannot authorize a second
+import over pending remote state, even if the committed head still matches the
+old baseline. Only the same journal may resume; automatic abandoned-attempt
+recovery remains unimplemented.
+
+Compare the writer head with the recorded baseline snapshot before the next
+import, then reconcile old IDs and hashes through its immutable Tag. This works
+without the prior local artifact and supports a branch moving backward or across
+history. Every target commit still comes from one full committed Git tree.
+
+An already published commit does not skip updating a different tracked branch.
+Validate that branch's own candidate, reuse the existing canonical commit Tag,
+and retain the candidate as the writer's exact baseline when the snapshot IDs
+differ. Never overwrite the canonical commit publication with another writer's
+snapshot. This also applies when a branch returns to a previously indexed commit.
+
+Branch search/resolve/read selects the last published Tag from the control record,
+including while the next import is pending. This promises the last indexed state,
+not the current Git tip. A first pending import has no searchable branch version.
+An ambiguous tracked branch/Git tag short name requires an explicit heads/tags ref.
+
 ### `versions` reads LambdaDB
 
 1. Resolve the repository Collection through remote metadata.
@@ -971,7 +1039,7 @@ Required meaningful checks:
 - Byte coverage, Unicode/BOM/CRLF/trailing-newline/long-line spans are exact.
 - Parse failures and huge nodes stay bounded and visible in reports.
 - B contains additions/replacements/deletions while A reads remain unchanged.
-- A controlled line-shift fixture updates positions and reuses identical embeddings.
+- A controlled line-shift fixture updates positions; managed imports may re-embed changed IDs, while the internal client-cache fixture verifies input-based reuse.
 - Different paths remain distinct even with identical bytes; reuse follows input.
 - Fixed-config mismatches fail before writes; fake vectors never enter a real corpus.
 - Explicit obsolete-ID deletion preserves replacement IDs and removes surplus chunks.

package/README.md

@@ -4,13 +4,24 @@ Version-aware code search on LambdaDB. Import a committed Git tree, search its
 chunks, and read exact source pinned to a validated immutable version.
 
 This is an experimental development CLI. Local fixture, fault-injection, SDK transport,
-and opt-in live acceptance checks are available. The npm package is prepared for
-publication but remains unpublished. See [VALIDATION.md](VALIDATION.md) for the latest observed results and
+and opt-in live acceptance checks are available. Development builds are available
+on npm under `@functional-systems/srcx@dev`. See [VALIDATION.md](VALIDATION.md) for the latest observed results and
 remaining scope, and [DESIGN.md](DESIGN.md) for the full design.
 
+## Install a development build
+
+Requires Node.js 22.14+ and Git. These are experimental prereleases; there is no
+stable release yet. Select the `dev` channel explicitly:
+
+```sh
+npm install -g @functional-systems/srcx@dev
+srcx --version
+srcx --help
+```
+
 ## Run locally
 
-Requires Node.js 22.14+ and Git. The initial preset uses lexical search with
+Requires Node.js 22.14+ and Git. The default preset uses lexical search with
 `embedding=none`; no embedding account or paid API is needed.
 
 ```sh
@@ -27,11 +38,11 @@ artifacts. It does not contact LambdaDB. The model's lexical matching is a test
 convenience, not a Lucene implementation or a relevance benchmark.
 
 All commands return JSON, except help and errors. Use `node dist/cli.js` in this
-checkout; `srcx` is the configured executable name for future distribution.
+checkout, or `srcx` after installing the npm package.
 
 For development branches, CI, and installed-package checks, see
 [CONTRIBUTING.md](CONTRIBUTING.md). Version channels, first-publication steps, and
-the initially disabled npm automation are documented in [RELEASING.md](RELEASING.md).
+npm automation are documented in [RELEASING.md](RELEASING.md).
 The project is licensed under [Apache-2.0](LICENSE).
 
 ## Preview a committed version without credentials
@@ -66,6 +77,92 @@ Chunks cover the exact source bytes, carry one-based line ranges, target 800 tok
 and stay below 1,500 tokens including path/symbol context. The internal window
 baseline is available to the test/build API, not as a public storage backend.
 
+## Opt into managed embeddings
+
+Supported models are `text-embedding-3-small` (1536 dimensions) and
+`text-embedding-3-large` (3072 dimensions), both cosine. Use either name with
+`--embedding`; each has a separate pinned preset and Collection. Existing small
+Collections keep their identity. Changing models requires a separate import.
+
+LambdaDB generates vectors for meaningful code, tests and prose. Imports-only
+and structural chunks remain lexical. The CLI uses LambdaDB credentials; it does not need an OpenAI key.
+Source text sent for embedding and semantic/hybrid queries pass through LambdaDB
+to OpenAI and incur usage charges. See [LambdaDB managed embeddings](https://docs.lambdadb.ai/guides/collections/managed-embeddings).
+
+```sh
+# Offline preview: no upload or embedding request.
+srcx import --path /path/to/repo --ref main --dry-run \
+  --embedding text-embedding-3-small --output /tmp/srcx-managed-preview
+
+# Creates a separate Collection; existing lexical Collections stay usable.
+srcx repo add --path /path/to/repo --embedding text-embedding-3-small
+# Use the exact collection value returned above, especially with multiple presets.
+srcx import --repo <collection> --ref main
+srcx search --repo <collection> --version main --query "retry failed writes" --mode hybrid
+srcx search --repo <collection> --version main --query "retry failed writes" --mode semantic
+```
+
+Connected imports, including `--dry-run --repo`, use the selected repository's
+pinned preset. `--embedding` on import is only for `--dry-run --path`.
+`search` keeps `--mode lexical` as its default; semantic and hybrid require a
+managed Collection. Hybrid uses LambdaDB RRF with identical filters on both legs.
+Existing result handles, lexical config hashes and publication journals stay valid.
+
+Local artifacts contain eligible `embeddingText` and input hashes, not vectors.
+`counts.managed` and `counts.managedTokens` estimate the complete corpus's eligible
+chunks and input tokens; `embedded=0` does not mean the server will skip them.
+Publication requires valid generated vectors in the immutable candidate Tag,
+plus the same exact payload/source checks as lexical publication. Unchanged
+records are not uploaded again. Changed file chunks and uncertain write retries
+may be embedded again; no global or query embedding cache is promised.
+
+A small synthetic live check is available after building:
+
+```sh
+npm run build
+node --env-file=.env.local scripts/live-managed.mjs
+```
+
+It uploads two synthetic commits, bounds document inputs to 10,000 estimated
+tokens and issues four managed search queries plus lexical checks. It retains a
+Collection, local fixture, artifacts, result handles and `.srcx/live-managed/report.json`.
+Completed reruns preserve the original report and make no service calls; changed
+runtime inputs require a fresh directory. Failed runs retain journals and reject
+automatic replay. These are correctness checks, not retrieval-quality measurements.
+
+## Evaluate retrieval quality
+
+The internal [lexical chunking pilot](https://github.com/lambdadb/srcx/blob/develop/eval/README.md) compares syntax-aware and
+window chunks on a fixed public corpus and 16 pinned investigation queries.
+`npm run eval:prepare` builds and validates the comparison offline. Live evaluation
+is an explicit separate operation and retains isolated evaluation Collections.
+
+The [default CLI workflow evaluation](https://github.com/lambdadb/srcx/blob/develop/eval/CLI-WORKFLOW.md)
+adds a second public repository and verifies real `search` → `read` results with
+the unchanged CLI preset. It uses normal repository Collections and separate local
+state; see its documented effects before opting into the live run.
+
+The [retrieval mode comparison](https://github.com/lambdadb/srcx/blob/develop/eval/RETRIEVAL-MODES.md) runs lexical, semantic and
+hybrid against the same managed corpora. It retains original and reviewed labels,
+full stdout accounting, command timings and bounded embedding request estimates.
+`npm run eval:modes:prepare` is offline; live execution is explicit and incurs
+managed embedding and LambdaDB usage.
+
+The [query-style diagnostic](https://github.com/lambdadb/srcx/blob/develop/eval/QUERY-STYLES.md)
+pairs identifiers, natural-language descriptions and mixed questions on eight new
+tasks. It adds rank-prefix and stdout-budget measurements without changing the
+model or ranking. [Embedding model candidates](https://github.com/lambdadb/srcx/blob/develop/eval/EMBEDDING-MODELS.md)
+separately describe possible follow-up comparisons and integration requirements.
+The [managed model comparison](https://github.com/lambdadb/srcx/blob/develop/eval/MODEL-COMPARISON.md)
+compares small and large on both frozen suites, including lexical controls.
+[Results](https://github.com/lambdadb/srcx/blob/develop/eval/MODEL-COMPARISON-RESULTS.md)
+show mixed gains and regressions; small remains the initial managed choice.
+
+[Transfer evaluation preparation](https://github.com/lambdadb/srcx/blob/develop/eval/TRANSFER-EVAL.md) adds source-verified,
+unreviewed Python/Go questions; no live retrieval has been run on them.
+New evaluation roots retain [safe command failure diagnostics](https://github.com/lambdadb/srcx/blob/develop/eval/COMMAND-DIAGNOSTICS.md)
+for explicit recovery.
+
 ## Explicit live acceptance run
 
 The live harness accepts `LAMBDADB_BASE_URL`, `LAMBDADB_PROJECT_NAME`, and
@@ -85,6 +182,25 @@ It saves connection settings under `.srcx/live/config.json` and keeps its state
 separate under `.srcx/live/state`. Rerunning resumes the saved synthetic run and
 refuses to reuse it against a different destination.
 
+For persistent Git branch acceptance, run `npm run test:live:branches`. It uses a
+separate synthetic Collection and `.srcx/live-branches/` state/report, covering
+in-place A/B updates, last-published reads during a pending update, shared commit
+Tags across two branches, rewinds, no-op imports, and SHA-only manual imports.
+From an isolated worktree, load the original checkout's env file explicitly:
+
+```sh
+npm run build
+node --env-file=/absolute/path/to/srcx/.env.local scripts/live-branches.mjs
+```
+
+The branch harness retains resources and resumes saved checkpoints on rerun.
+It preserves the original source revision and completion time. Checkpoints from
+different runtime code, harness, fixture, lockfile, or Node version are rejected
+before connecting or overwriting evidence. To validate changed code, select a new
+`SRCX_LIVE_BRANCHES_DIR` (for example `.srcx/live-branches-next`); retain the old
+run and any pending journal. Its per-import deadline defaults to 300 seconds and accepts
+`SRCX_LIVE_TIMEOUT_MS` up to 600000. Do not delete pending journals to start over.
+
 ## Connected workflow
 
 These commands create and write LambdaDB resources. Select an approved project
@@ -104,6 +220,11 @@ node dist/cli.js repo show --repo <name>
 # Import the exact artifact reviewed in the credential-free preview.
 node dist/cli.js import --repo <name> --artifact /tmp/srcx-build-a
 node dist/cli.js versions --repo <name>
+
+# Keep a Git branch connected to its Collection Branch.
+node dist/cli.js import --repo <name> --ref develop
+node dist/cli.js search --repo <name> --version develop --query retry
+node dist/cli.js resolve --repo <name> --ref refs/heads/develop
 node dist/cli.js search --repo <name> --version <full-commit-A> --query retry
 node dist/cli.js read --result <result-id> --context 20
 node dist/cli.js read --result <result-id> --full-file
@@ -141,10 +262,28 @@ are one-based and inclusive.
 ## Publication and recovery
 
 The control Branch `main` holds descriptors/version summaries. `checkpoint-empty`
-is forked before any control write. Each import uses a new `work-*` Branch,
-optionally forked from the last locally retained, remotely validated writer
-baseline. Writers are frozen after publication. A fresh local state can start a
-full import from `checkpoint-empty`; source data is never forked from a Tag.
+is forked before any control write. Importing a Git branch creates or updates its
+stable `git-*` Collection Branch, derived from the full `refs/heads/...` name.
+Git `main` also uses a `git-*` Branch; Collection `main` remains control-only.
+Each later import reconciles against that branch's last validated snapshot,
+including deletions and non-fast-forward changes. Branches sharing a commit share
+one canonical `ver-*` Tag while retaining their own writer snapshots.
+
+`search/read --version develop` and `resolve --ref develop` select the branch's
+last successfully published commit Tag. During an import or after a failed update,
+they keep serving the previous published commit; the first import is unavailable
+until publication. This is the last indexed state, not a live Git HEAD lookup.
+Nothing polls or fetches Git automatically: run import again to advance the branch.
+If an indexed branch and synchronized Git tag share a short name, use
+`refs/heads/<name>` or `refs/tags/<name>` explicitly. Known Git names take precedence
+over commit prefixes.
+
+A commit SHA or Git tag import does not infer a containing branch. An unpublished
+commit uses a fresh `work-*` Branch, optionally forked from a validated previous
+manual writer; an already published commit reuses its Tag. Manual writers remain
+frozen. Source data is never forked from a Tag. A clean tracked branch can be
+updated from fresh local state using its remote baseline. Local build reuse is
+cached separately for each Git branch and for manual imports.
 
 The importer deletes obsolete IDs, upserts changed records and inventory parts in
 bounded sequential requests, then sends `__manifest__` **alone** after every prior
@@ -156,7 +295,10 @@ an early/stale snapshot even after the marker is observed.
 
 A per-Collection local lock and durable `pending.json` journal prevent another
 commit from overwriting a partial attempt. Only one importing host is supported.
-After a timeout or unknown write result, retain the artifacts and journal:
+A tracked branch also records pending import ownership in control `main` before
+writing code. If the local journal is lost, new local state refuses to overwrite
+that pending branch even when its committed head has not advanced yet. After a
+timeout or unknown write result, retain the artifacts and journal:
 
 ```sh
 node dist/cli.js import --repo <name> --artifact /path/from/pending.json \
@@ -184,8 +326,17 @@ For search and resolve, a synchronized Git tag name takes precedence over a comm
 prefix, matching Git import's tag-before-OID rule. A pending tag fails explicitly
 instead of falling back to a matching commit prefix. Use `refs/tags/<name>` to
 select a Git tag explicitly.
-Explicit authoritative pruning and persistent tracked-branch synchronization are
-follow-up work; no full history import is required.
+Automatic Git observation, authoritative pruning, branch rename/deletion handling,
+and garbage collection remain follow-up work; no full history import is required.
+
+Existing commit Tags and frozen `work-*` Branches remain valid. The next import
+using a Git branch name establishes its fixed mapping, even if that commit was
+already published. A pending journal from the previous implementation resumes on
+its original `work-*` writer; import the branch again after recovery to establish
+tracking. `--artifact` uses the Git branch recorded when the artifact was built,
+with its pinned commit; it does not reread the branch's current tip. The publication
+JSON continues to describe the canonical commit Tag: its `writer` can be the
+original publishing branch when multiple Git branches share that commit.
 
 ## State and implementation map
 

package/RELEASING.md

@@ -2,12 +2,19 @@
 
 ## Current state
 
-The source is prepared as `@functional-systems/srcx@0.1.0-dev.1` under Apache-2.0.
-It has not been published to npm. `private: false` permits a reviewed first
-publication; it does not establish registry availability or distribution readiness.
-`NPM_DEV_PUBLISH_ENABLED` is initially `false`. No stable/rc release or Homebrew
-formula has been published. Local/live application evidence is in
-[VALIDATION.md](VALIDATION.md); it is separate from package publication evidence.
+The initial `@functional-systems/srcx@0.1.0-dev.1` package was published publicly
+from reviewed commit `f94f947bf593b2f8498c07e130933b0ab444f868`. Its exact tarball
+passed clean-install and live LambdaDB checks. The local bootstrap has no GitHub
+Actions provenance. npm created both `dev` and `latest` at that prerelease; select
+`@dev` explicitly. No stable/rc release or Homebrew formula has been published.
+
+The package-specific Trusted Publisher is configured for `lambdadb/srcx` and
+`publish.yaml`, with direct publication allowed. `NPM_DEV_PUBLISH_ENABLED=true`.
+The first successful [OIDC publication](https://github.com/lambdadb/srcx/actions/runs/36035063463/attempts/3)
+produced `0.1.0-dev.3` from the same commit and moved `dev` to that version.
+Provenance identifies this repository, workflow, commit, and run. The current
+`latest` remains the bootstrap prerelease `0.1.0-dev.1`; it is not a stable release.
+See [VALIDATION.md](VALIDATION.md) for registry and consumer verification.
 
 This workflow follows [LambdaDB CLI](https://github.com/lambdadb/lambdadb-cli/blob/develop/RELEASING.md).
 The repository keeps Prettier plus strict TypeScript checks as its existing lint
@@ -26,7 +33,8 @@ version entries in `package-lock.json` together, for example using
 `npm version VERSION --no-git-tag-version`. CLI `--version` reads package metadata.
 For explicit releases, add a dated `## [VERSION] - YYYY-MM-DD` changelog section.
 The GitHub tag must match the version, and the prerelease flag must match its channel.
-`latest`, not the tip of `main`, identifies the stable npm release.
+After the first stable release, `latest` identifies the stable npm release;
+the bootstrap exception is recorded above.
 
 The checked-in development base starts at `0.1.0-dev.1`. During an eligible push,
 `scripts/dev-release.mjs` replaces `N` with the full history's first-parent commit
@@ -64,7 +72,8 @@ Do not republish, overwrite versions, or move release tags to work around lag.
 
 ## First publication and Trusted Publisher setup
 
-Complete these steps from a reviewed, validated commit after this setup PR merges:
+The initial bootstrap is complete. The procedure below documents first-time setup
+and the checks required before declaring automatic publication operational:
 
 1. Verify npm ownership for the `functional-systems` scope and the package name.
    GitHub organization membership does not establish npm permissions.