@functional-systems/lambdadb-cli 0.1.3 → 0.1.4-dev.17

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## [Unreleased]
 
+### Maintenance
+
+- Synchronize the 0.1.3 release history and start the 0.1.4 development line.
+- Prepare the Homebrew formula for verified stable 0.1.3 and record publication evidence.
+
 ## [0.1.3] - 2026-10-06
 
 ### Added
@@ -143,6 +148,5 @@ Published publicly on npm's `dev` channel on 2026-09-18 as the manual bootstrap.
 The initial OIDC build `0.1.0-dev.4` followed from the same reviewed develop
 commit; generated dev versions do not create separate source changelog entries.
 Automatic dev publication is enabled. The observed `latest` tag remains at the
-bootstrap until a reviewed stable release replaces it. Publication, provenance,
-installation and development-project smoke evidence are recorded in VALIDATION.md.
+bootstrap until a reviewed stable release replaces it.
 Main promotion is required only for rc/stable.

package/CONTRIBUTING.md

@@ -66,16 +66,12 @@ development base in that synchronization PR so develop retains a dev version.
 
 A separate `release/*` branch can be created from reviewed develop and target
 main when preparing rc/stable metadata while develop retains its automatic dev
-base. The first stable release used `release/0.1.0` for this reason. Do not merge
-stable package metadata into develop without setting its next dev base, because
-automatic development publication requires an `X.Y.Z-dev.N` version.
+base. Do not merge stable package metadata into develop without setting its next
+dev base, because automatic development publication requires an `X.Y.Z-dev.N`
+version.
 
 The first npm bootstrap, rc/stable tags and GitHub Releases remain explicit
-release actions. Subsequent dev publication is automatic once enabled.
-Bootstrap `0.1.0-dev.1` and the first OIDC development publication `0.1.0-dev.4`
-were verified on 2026-09-18; automatic dev publication is enabled. Publication,
-provenance and development-project smoke evidence are recorded in
-[VALIDATION.md](VALIDATION.md). Follow
+release actions. Subsequent dev publication is automatic once enabled. Follow
 [RELEASING.md](RELEASING.md) for package preparation, version/channel rules,
 credentialed live evidence, initial npm bootstrap and Trusted Publishing.
 Local tests and PR validation alone never trigger publication.
@@ -89,8 +85,8 @@ review requirements.
 Never commit project keys, `.env` files or signed URLs. Runtime tests use loopback
 servers with synthetic credentials. Live tests require an explicitly designated
 development project and credential set; local or CI success is not proof of
-live-service readiness. See [README.md](README.md) and
-[VALIDATION.md](VALIDATION.md) for the current contract and evidence boundaries.
+live-service readiness. See [README.md](README.md) for public behavior and the
+[validation scope](#validation-scope) below for evidence boundaries.
 
 ## Compatibility and maintenance
 
@@ -104,3 +100,92 @@ Review dependency updates through the same PR checks, including the actual SDK
 contract and installed-package tests. Keep workflow actions pinned to commit
 SHAs and document version updates in their comments. Do not copy another
 repository's runtime matrix or release tooling without checking this CLI's needs.
+
+## Validation scope
+
+- `npm test` builds the CLI and executes unit, subprocess and release-tooling
+  contracts. Loopback HTTP servers exercise the installed SDK without contacting
+  LambdaDB: input and target precedence, query and Collection mapping, signed
+  transfers, pagination, complete results, credential redaction and exit codes.
+  Failure cases cover bounded inputs, timeouts, cancellation, partial and unknown
+  writes, and the absence of mutation retries.
+- `npm run test:package` packs the candidate, checks its inventory and executable,
+  installs it into a temporary consumer and repeats the CLI contracts against
+  that artifact. To check an existing candidate, use
+  `npm run test:package -- /path/to/package.tgz`. Building test sources alone is
+  not evidence that tests executed.
+- [Homebrew validation](packaging/homebrew/README.md#local-and-ci-verification)
+  checks the stable formula's installation and released CLI contracts on macOS
+  and Linux. A new installation does not establish an existing-user upgrade;
+  verify upgrades separately as part of the tap handoff.
+- Local tests and PR CI do not establish backend deployment provenance, live
+  search quality, production performance, billing readiness, exactly-once writes
+  or durable resume. Check the deployed backend revision separately when a
+  feature requires server support. The CI matrix does not validate Windows
+  permissions or signals.
+- Input byte/document limits bound accepted input, not process memory. Large
+  mock responses and a bounded live sample are not exhaustive memory or storage
+  policy tests. A successful live sample applies only to its designated target,
+  revision, refs and inputs.
+
+## Live validation
+
+Provision a disposable development project/key outside this tool, with Collection
+create/update/delete, ordinary and bulk write, and query/fetch access.
+Supply the key through secure shell input or a secret manager, never in history.
+
+```sh
+export LAMBDADB_ENDPOINT=https://YOUR_DEV_API_ORIGIN
+export LAMBDADB_PROJECT=YOUR_DEV_PROJECT
+# Inject LAMBDADB_API_KEY securely; no .env file is loaded automatically.
+export LAMBDADB_RUN_LIVE_TESTS=1
+export LAMBDADB_LIVE_CONFIRM_PROJECT="$LAMBDADB_PROJECT"
+npm run test:live
+```
+
+The test fails before API calls when required settings are absent. It creates a
+random temporary collection, imports two 3 MiB documents plus a bulk document,
+accepts and verifies metadata for all 49 fixed analyzer presets, checks exact
+facet-only and document+facet buckets, and checks committed query/fetch contents
+with a maximum 300-second observation window per stage. It also checks managed
+reranking with default criteria, null and custom criteria, including
+final/retrieval scores and status metadata.
+It creates two additional temporary Collections for native embedding-only and
+legacy true inputs. It exercises actual CLI create/update, normalized metadata,
+document/query embedding generation, ordinary retrieval,
+Bayesian candidate budgets, default/explicit rerank budgets, null rerank and
+server-side rejection of invalid Bayesian requests. All three Collections are
+cleaned up with subsequent HTTP 404 verification.
+
+Request timeouts and polling sleeps are capped to the remaining budget, and
+responses at or after the deadline cannot pass. Process termination
+and event-loop scheduling may delay reporting. It reports elapsed time and
+matched-document counts; a timeout is a failed smoke, not proof that accepted
+writes were rejected or lost.
+
+Collection cleanup uses the SDK because deletion is outside the public CLI MVP.
+Only the test's own Collections are eligible for cleanup. An interrupted process
+or failed cleanup may leave those Collections; inspect them manually.
+
+This sample does not prove global index readiness, ranking quality, every ref's
+live behavior, or exactly-once writes. A large result alone does not prove the
+service selected docsUrl; mock tests explicitly exercise that transport path.
+Use existing known development tag/alias refs for additional live ref evidence.
+
+## Recording verification results
+
+Keep repeatable procedures and supported behavior in repository documentation.
+Put each change's exact commands, outcomes, source/artifact revision, CI links,
+live target and cleanup result, and material unperformed checks in its PR.
+For publication, include the verified version, integrity and provenance summary
+in the release PR or GitHub Release. User-facing changes and compatibility notes
+belong in the changelog and release notes.
+
+Retain sanitized evidence needed for long-term review as release assets or in
+an approved durable location; CI logs and artifacts have retention limits, and
+local temporary paths are not durable references. Never include credentials or
+signed URLs. Historical repository records remain available through Git history.
+
+Do not append per-run logs, release-status snapshots or successful test counts to
+maintainer guides. A completed verification does not require another documentation
+PR. Update these guides when procedures, requirements or supported behavior change.

package/DESIGN.md

@@ -56,8 +56,9 @@ preserves `facets` while removing the consumed signed URL. Facet field names joi
 other user-defined maps in credential redaction, including collision preservation;
 fixed facet result/bucket keys retain their SDK schema even for short credentials.
 Loopback subprocess tests cover serialization and output through the published SDK,
-and the installed-tarball suite repeats these contracts. Live evidence is separate
-in [VALIDATION.md](VALIDATION.md).
+and the installed-tarball suite repeats these contracts. Live validation is
+separate; follow the [contributor procedure](CONTRIBUTING.md#live-validation)
+and record results in the relevant PR.
 
 ## SDK 0.7.0 contract update (2026-10-04)
 

package/README.md

@@ -19,11 +19,11 @@ lambdadb --help
 ```
 
 For reproducible CI runs, pin an exact published version such as
-`@functional-systems/lambdadb-cli@0.1.2`. To try development builds, explicitly use
+`@functional-systems/lambdadb-cli@0.1.3`. To try development builds, explicitly use
 `@functional-systems/lambdadb-cli@dev`; this moving channel contains prereleases.
 Installed CLIs do not update themselves. See
-[RELEASING.md](RELEASING.md#current-status) for release status and
-[VALIDATION.md](VALIDATION.md) for verification results and remaining limitations.
+[GitHub Releases](https://github.com/lambdadb/lambdadb-cli/releases) and
+[CHANGELOG.md](CHANGELOG.md) for published changes and compatibility notes.
 
 ### Homebrew
 
@@ -447,7 +447,8 @@ Tests execute the real CLI and installed SDK against loopback HTTP servers. They
 cover the complete first-use flow, ref forwarding, signed transfers, pagination,
 partial and unknown writes, validation, output, credentials and exit codes.
 They do not contact a LambdaDB service. See [DESIGN.md](DESIGN.md) for contract
-evidence and [VALIDATION.md](VALIDATION.md) for measured verification scope.
+decisions and [CONTRIBUTING.md](CONTRIBUTING.md#validation-scope) for validation
+methods and their limits.
 
 This MVP intentionally omits Branch/Tag/Alias management: default `main` supports
 first use, while reads can select existing refs. It also omits Console management,
@@ -457,9 +458,10 @@ plugins and publication. There are no changes to the SDK or reference repositori
 Live verification requires an explicitly designated development project, endpoint
 and project key. Do not discover or borrow credentials from another repository.
 Use `npm run test:live` with the explicit opt-in settings in
-[RELEASING.md](RELEASING.md#explicit-live-smoke). It exercises ordinary/bulk import
-and committed query/fetch contents in a random temporary collection, then uses
-the SDK to clean up that collection. The normal test suite and CI never run it.
+[CONTRIBUTING.md](CONTRIBUTING.md#live-validation). It exercises ordinary/bulk
+import, query/fetch, native embeddings and Bayesian reranking in temporary
+Collections, then uses the SDK to delete them and verify their absence. The normal
+test suite and CI never run it.
 
 ## License
 

package/RELEASING.md

@@ -1,103 +1,9 @@
 # Releasing LambdaDB CLI
 
-## Current status
-
-CLI 0.1.3 is prepared on `release/0.1.3` from reviewed develop commit
-`caee1bcb6ce864c33647673b54a48f7cc06dcf84` ([PR #18](https://github.com/lambdadb/lambdadb-cli/pull/18)).
-It pins SDK 0.8.0 and adds Bayesian JSON queries, native embedding configuration
-and Collection index updates. Existing search defaults and error/output contracts
-are preserved. See [candidate validation](VALIDATION.md#cli-013-release-preparation-2026-10-06).
-This is release preparation; stable npm and the public Homebrew tap remain at
-0.1.2. Merge the release PR with a merge commit to preserve develop ancestry.
-Tag creation, GitHub Release publication and npm latest promotion require the
-explicit authorization described below.
-
-### Latest published stable release
-
-CLI 0.1.2 was published on 2026-10-04 from merged main commit
-`6628fe0ed1f405c88fbd91d591e5223d3250dd73` through
-[GitHub Release v0.1.2](https://github.com/lambdadb/lambdadb-cli/releases/tag/v0.1.2)
-and the [successful OIDC workflow](https://github.com/lambdadb/lambdadb-cli/actions/runs/37191188846).
-It pins SDK 0.7.0 and includes 49 fixed analyzer presets, optional per-query
-managed reranking and credential-safe fixed rerank metadata.
-
-At stable publication, independent registry verification confirmed latest=0.1.2
-and dev=0.1.2-dev.12.
-The published tarball is byte-identical to the reviewed, live-tested candidate.
-A clean registry consumer passed all 46 CLI contracts, version/help, SDK version,
-integrity, four registry signatures and three attestations. Decoded provenance
-identifies the release commit, tag and workflow. See
-[publication evidence](VALIDATION.md#cli-012-publication-2026-10-04).
-
-[PR #16](https://github.com/lambdadb/lambdadb-cli/pull/16) synchronized main into
-develop with the 0.1.3-dev.1 base. Its successful automatic publication produced
-0.1.3-dev.13; an independent registry consumer passed all 46 CLI contracts,
-integrity, signature and provenance checks. At verification, dev=0.1.3-dev.13
-and latest=0.1.2.
-
-[Homebrew PR #6](https://github.com/lambdadb/homebrew-tap/pull/6) merged the matching
-0.1.2 formula. Public-tap installation passed on macOS arm64 and Linux x86_64.
-A separate disposable-tap macOS arm64 upgrade from 0.1.1 to 0.1.2 also passed;
-existing-user public-tap upgrades and Linux upgrades were not tested. See
-[post-release evidence](VALIDATION.md#cli-012-post-release-verification-2026-10-04).
-Publication and bounded development smoke do not establish production deployment,
-search quality, load/failure coverage or billing readiness.
-
-## CLI 0.1.1 publication
-
-CLI 0.1.1 was published on 2026-09-29 through
-[GitHub Release v0.1.1](https://github.com/lambdadb/lambdadb-cli/releases/tag/v0.1.1)
-and the [OIDC release workflow](https://github.com/lambdadb/lambdadb-cli/actions/runs/36557578359).
-Tag/main commit `80a4c10628ad2ad4ebf8d90a01924d27dcb4a790` has the same tree as
-reviewed candidate `0291970`. The workflow passed on attempt 1, including Node
-22/24 validation and tests of the exact publication tarball.
-
-Registry reads confirmed `latest=0.1.1`, while `dev=0.1.1-dev.10` remained unchanged.
-A clean unqualified npm installation selected CLI 0.1.1 and SDK 0.6.0, passed all
-40 CLI contracts and verified registry signatures and attestations. The published
-tarball is byte-identical to the tested final candidate; provenance identifies the
-release commit, tag and workflow. See [VALIDATION.md](VALIDATION.md#cli-011-publication).
-
-The 0.1.1 post-release synchronization started the `0.1.2-dev.1` development base
-and prepared the 0.1.1 Homebrew formula. The public tap matched that formula at
-the pre-release check on 2026-10-04; the completed 0.1.2 handoff is recorded above.
-Facets still require a supporting server and newly built keyword indexes;
-publication does not migrate Collections or upgrade installed CLIs.
-
-## Prior publication status
-
-The first stable version, `0.1.0`, was published on 2026-09-19 through
-[GitHub Release v0.1.0](https://github.com/lambdadb/lambdadb-cli/releases/tag/v0.1.0)
-and the [OIDC release workflow](https://github.com/lambdadb/lambdadb-cli/actions/runs/35421226854).
-Tag and main release commit `c8d389f` have the same tree as the reviewed and
-live-tested candidate `658ea7c`. The workflow passed on attempt 1, including Node
-22/24 validation and tests of the exact publication tarball.
-
-Registry verification confirmed `latest=0.1.0` and `dev=0.1.0-dev.5`. A clean,
-unqualified npm install passed all 35 CLI contracts, version/help, integrity,
-provenance and signature checks. Version/tag and attestation metadata propagated
-separately; verification used read retries without republishing.
-
-The post-release synchronization merged main history back into develop with
-`0.1.1-dev.1` as its development base. After the Homebrew documentation merge,
-[develop CI](https://github.com/lambdadb/lambdadb-cli/actions/runs/35434313586)
-published and verified `0.1.1-dev.8` from `225dec3` on 2026-09-19. Registry and
-provenance metadata identify that commit; `latest` remains `0.1.0`. Development
-builds do not require a separate stable release or tag.
-
-Bootstrap `0.1.0-dev.1` and the first OIDC development builds were verified on
-2026-09-18. The ordinary develop merge published `0.1.0-dev.5` in
-[one successful attempt](https://github.com/lambdadb/lambdadb-cli/actions/runs/35344153978),
-handling approximately three minutes of registry propagation without another write.
-The bootstrap initially assigned `latest` to `0.1.0-dev.1`, and a removal attempt
-returned HTTP 400. The stable publication replaces that temporary tag state.
-Do not repeat bootstrap or change tags to work around propagation delays.
-
-These are dated validation milestones, not a continuously updated version list.
-Check npm for current dist-tags. Apache-2.0 licensing, publication, provenance,
-consumer checks and development-project smoke evidence are recorded in
-[VALIDATION.md](VALIDATION.md). Automatic dev publication is enabled;
-future stable/rc tags and GitHub Releases remain explicit release actions.
+This guide defines release policy and procedures. User-facing changes belong in
+[CHANGELOG.md](CHANGELOG.md) and [GitHub Releases](https://github.com/lambdadb/lambdadb-cli/releases).
+Record execution results in the relevant PR and release, following
+[Recording verification results](CONTRIBUTING.md#recording-verification-results).
 
 ## Branch and version policy
 
@@ -206,8 +112,8 @@ compatible. Human summaries are not a scripting interface.
 
 3. Run the live smoke below against an explicitly designated development project.
    Record commit, SDK version, endpoint/project, command, outcome and cleanup
-   without keys or signed URLs. Missing credentials are a blocked release
-   prerequisite, not a skipped success. PR CI deliberately has no service keys.
+   in the release PR without keys or signed URLs. Missing credentials are a blocked
+   release prerequisite, not a skipped success. PR CI deliberately has no service keys.
 4. For rc/stable releases, promote to main by reviewed PR with required CI
    checks. The first development bootstrap can use reviewed develop directly.
    Re-run checks/live smoke if release contents changed. Record the verified
@@ -225,7 +131,8 @@ compatible. Human summaries are not a scripting interface.
 7. Verify the workflow, npm version/dist-tag, provenance's repository/commit and
    a clean consumer install of the exact version. Test the installed binary's
    version/help and basic JSON behavior. Confirm a dev/rc release did not move
-   `latest`. Synchronize release-only main changes back to develop by PR.
+   `latest`. Add the verification summary and links to the release PR or GitHub
+   Release. Synchronize release-only main changes back to develop by PR.
 
 Useful read-only checks after publication:
 
@@ -246,8 +153,8 @@ Trusted Publishers are package-specific. The SDK's configuration does not cover
 this CLI. npm requires an existing package before configuring its trust policy.
 See the official [npm trust prerequisites](https://docs.npmjs.com/cli/v11/commands/npm-trust/).
 
-This one-time bootstrap was completed for this package on 2026-09-18. The steps
-below document setup and recovery; do not repeat the bootstrap for normal dev builds.
+This package is already bootstrapped. The steps below document initial setup;
+do not repeat the bootstrap for an existing package or normal dev builds.
 For a new package, first complete the reviewed release preparation and preflight.
 An authorized npm organization owner performs the bootstrap from the verified
 develop commit, using interactive `npm login` and the account's MFA, then
@@ -289,45 +196,9 @@ this direct-publish workflow. See [npm Trusted Publishing](https://docs.npmjs.co
 
 ## Explicit live smoke
 
-Provision a disposable development project/key outside this tool, with create,
-ordinary and bulk write, query/fetch and temporary-collection delete access.
-Supply the key through secure shell input or a secret manager, never in history.
-
-```sh
-export LAMBDADB_ENDPOINT=https://YOUR_DEV_API_ORIGIN
-export LAMBDADB_PROJECT=YOUR_DEV_PROJECT
-# Inject LAMBDADB_API_KEY securely; no .env file is loaded automatically.
-export LAMBDADB_RUN_LIVE_TESTS=1
-export LAMBDADB_LIVE_CONFIRM_PROJECT="$LAMBDADB_PROJECT"
-npm run test:live
-```
-
-The test fails before API calls when required settings are absent. It creates a
-random temporary collection, imports two 3 MiB documents plus a bulk document,
-accepts and verifies metadata for all 49 fixed analyzer presets, checks exact
-facet-only and document+facet buckets, and checks committed query/fetch contents
-with a maximum 300-second observation window per stage. It also checks managed reranking with default criteria, null
-and custom criteria, including final/retrieval scores and status metadata.
-The SDK 0.8.0 extension creates two additional temporary Collections for native
-embedding-only and legacy true inputs. It exercises actual CLI create/update,
-normalized metadata, document/query embedding generation, ordinary retrieval,
-Bayesian candidate budgets, default/explicit rerank budgets, null rerank and
-server-side rejection of invalid Bayesian requests. All three Collections are
-cleaned up with subsequent HTTP 404 verification.
-Request timeouts and polling sleeps are capped to the remaining
-budget, and responses at or after the deadline cannot pass. Process termination
-and event-loop scheduling may delay reporting. It reports elapsed time and
-matched-document counts; a timeout is a failed smoke, not proof that accepted
-writes were rejected or lost.
-Collection cleanup uses the SDK because deletion is outside the public CLI MVP.
-The harness verifies deletion with a subsequent HTTP 404.
-Only the test's own collection is eligible for cleanup. An interrupted process
-or failed cleanup may leave that named collection; inspect it manually.
-
-This sample does not prove global index readiness, ranking quality, every ref's
-live behavior, or exactly-once writes. A large result alone does not prove the
-service selected docsUrl; mock tests explicitly exercise that transport path.
-Use existing known development tag/alias refs for additional live ref evidence.
+Follow the [live validation procedure](CONTRIBUTING.md#live-validation) and record
+its result in the release PR. It is a release prerequisite; ordinary PR CI has
+no service credentials and cannot establish live readiness.
 
 ## Homebrew handoff
 
@@ -338,22 +209,7 @@ commit. Development publication does not update Homebrew. After each stable npm
 release, follow the [Homebrew maintainer guide](https://github.com/lambdadb/lambdadb-cli/tree/develop/packaging/homebrew#readme) to
 update checksums, pass installation checks and prepare a tap PR. Tap publication
 is separate from this repository's npm workflow; no cross-repository write or
-automatic tap update is configured. The public
-[LambdaDB tap](https://github.com/lambdadb/homebrew-tap) provides stable `0.1.2`
-(verified on 2026-10-04). Public installation and disposable-tap upgrade evidence
-is recorded in [VALIDATION.md](VALIDATION.md#cli-012-post-release-verification-2026-10-04).
-
-## Design references
-
-- LambdaDB TypeScript client `RELEASING.md` and `publish.yaml`: canonical channels,
-  separate live evidence, same tested artifact and OIDC. This CLI intentionally
-  publishes dev from develop, while rc/stable releases require main history.
-- LambdaDB migration `.goreleaser.yml`/release workflow and `install.sh`: verify
-  installed artifacts and explicit versions. Go binaries, GoReleaser and Docker
-  distribution are unnecessary for this npm CLI's first release.
-- [Command Line Interface Guidelines](https://clig.dev/): preserve machine output,
-  separate diagnostics, avoid interactive CI requirements, protect secrets and
-  test cancellation. The CLI contract suite exercises these boundaries.
-
-External documentation checked on 2026-09-18. Consult current npm documentation
-when configuring the package; registry requirements can change independently.
+automatic tap update is configured. Record installation and actual upgrade results
+in the tap PR, including tested platforms and any unperformed checks. Query the
+[public tap](https://github.com/lambdadb/homebrew-tap) for its current formula;
+do not maintain a second release-status history here.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@functional-systems/lambdadb-cli",
-  "version": "0.1.3",
+  "version": "0.1.4-dev.17",
   "private": false,
   "description": "Project-scoped LambdaDB command-line tools",
   "type": "module",
@@ -12,7 +12,6 @@
     "src",
     "README.md",
     "DESIGN.md",
-    "VALIDATION.md",
     "CONTRIBUTING.md",
     "examples",
     "RELEASING.md",
@@ -52,5 +51,6 @@
   "bugs": {
     "url": "https://github.com/lambdadb/lambdadb-cli/issues"
   },
-  "license": "Apache-2.0"
+  "license": "Apache-2.0",
+  "gitHead": "b2a52489a5893198466850e221a2cc4bcde79bd3"
 }