@vectros-ai/cli 0.12.0 → 0.14.0

package/AUTHORING.md

@@ -78,7 +78,11 @@ A name must be 2–50 chars: a lowercase letter, then lowercase letters / digits
 ```
 
 `bootstrap` shows the same plan and asks for confirmation before minting
-(`--yes` skips the prompt for CI/agents; `--print` previews without minting).
+(`--yes` skips the prompt for CI/agents). ⚠️ **`--no-merge` is NOT a dry run** — it still
+mints/reconciles for real; it only changes where the resulting credential goes, printing the MCP
+config snippet to stdout instead of merging it into your client's config file. To preview without
+touching your account, stop at `blueprint plan` (offline) — `bootstrap`, with or without `--no-merge`,
+always applies.
 
 **Provisioning a production context — `--no-seed`.** A blueprint's `seed`
 records are illustrative sample data: handy for a getting-started or demo
@@ -120,7 +124,10 @@ contextId: mcp          # 3-31 chars, lowercase-start. The app-context the key b
 schemas:
   - typeName: thing   # immutable after first apply
     displayName: Thing
-    indexMode: HYBRID    # HYBRID (default) | SEMANTIC | TEXT
+    indexMode: HYBRID    # HYBRID | SEMANTIC | TEXT | NONE (store-only).
+                         # Omitting it does NOT mean HYBRID: a record schema with no
+                         # indexMode resolves to NONE, and a document schema with none
+                         # is rejected. Declare the mode you want.
     fields:
       - fieldId: title
         fieldType: string       # string | number | boolean | date | enum | array | object | reference
@@ -134,7 +141,9 @@ schemas:
         required: true
     lookupFields: [title]        # extra O(1) exact-match lookup indexes (max 10);
                                  # object form { fieldName, unique?, rangeEnabled?,
-                                 # sortBy?, allowOverflow? } for constraints/range.
+                                 # sortBy?, allowOverflow? } for constraints/range, or
+                                 # { fieldNames: [a, b], sortBy?, allowOverflow? } for
+                                 # a composite (conjunctive) lookup over 2-3 fields.
                                  # externalId has a built-in finder — don't list it.
     capabilities: { auditHistory: true }   # default true; surfaced for a self-documenting audit posture
 
@@ -191,12 +200,15 @@ before customers build on the schema. Three knobs, each permanent:
   set `allowOverflow: true` on it, which accepts a higher-cost secondary index.
   Keep equality lookups lean.
 
-- **`sortBy` — the order results come back in.** For an *equality* lookup,
-  `sortBy` sets the listing order: `createdAt` (default), `lastUpdated`, or a
-  declared field. *Trap:* sorting by an **optional** payload field silently drops
-  records that don't have it from that lookup — and it's locked. Use `createdAt`/
-  `lastUpdated` (always present) unless every record is guaranteed to carry the
-  field.
+- **`sortBy` — the order results come back in, and what a sort-key window
+  narrows.** For an *equality* lookup, `sortBy` sets the listing order:
+  `createdAt` (default), `lastUpdated`, or a declared field. It is also what
+  `sortFrom`/`sortTo` bound when you narrow a `value` lookup. An **optional**
+  field is fine: records that don't carry it are listed ahead of those that do,
+  and a bounded window never includes them. *Locked:* `sortBy` itself AND the
+  sorted field's declared `fieldType` are both migration-locked — pick a new field
+  name if you need to change either. An `array`/`object` field is rejected as a
+  `sortBy` target (no meaningful order).
 
 **Sensitive fields can still be looked up — by exact match only.** A
 `sensitive` field is HMAC'd into a per-tenant **blind index**, so you *can* list
@@ -205,6 +217,49 @@ without the value ever being stored in the clear or entering the search index. A
 blind hash is not orderable, so a sensitive lookup **cannot** be `rangeEnabled`,
 and no lookup's `sortBy` may name a sensitive field (the platform rejects both).
 
+### Composite (conjunctive) lookups — matching several fields at once
+
+`{ fieldNames: [a, b] }` (2-3 fields) matches ALL of them together in one clause —
+"every record where `status` is `open` **and** `area` is `billing`" — exact,
+complete, in the declared order. This is a different query shape from declaring
+`status` and `area` as two separate equality lookups: two separate lookups can
+each tell you "records with this status" or "records with this area", but never
+"records with both", short of fetching one side and filtering client-side.
+
+```yaml
+lookupFields:
+  - externalId
+  - { fieldNames: [status, area], sortBy: createdAt, allowOverflow: true }
+```
+
+Like a single-field lookup, the shape is **migration-locked** at create — the same
+"decide deliberately" rule as above applies, doubly so here since a composite
+also can't be swapped for two plain lookups later without a new field name.
+Rules the platform enforces, all offline-checkable and caught by `blueprint
+validate` before they'd 400 at `bootstrap`:
+
+- **2-3 fields, order significant.** A query may match a leading run of the list
+  (the first field alone, the first two together, …) but never a later field
+  alone — declare a separate lookup for that. No leg may repeat.
+- **Each leg must be a scalar, single-valued field** — not `array`/`object`, and
+  not a `many`-cardinality `reference`. A leg occupies one sort-key position and
+  holds one value; a multi-valued field there would index only one rendering and
+  the conjunction would silently return a subset while looking complete.
+  Cardinality-`one` references are fine.
+  - **A leg can't ALSO be its own `sortBy` target**, on this same lookup or a
+    separate one that treats that field as `rangeEnabled`. Within a fixed tuple
+    every matching record has the same value for that leg, so ordering by it (or
+    range-querying it) is meaningless — pick a different field, `createdAt`, or
+    `lastUpdated`.
+- **`unique`/`rangeEnabled` are not available on a composite** — it's an
+  exact-match index over its fields; declare a range lookup separately if you
+  need one. `sortBy` and `allowOverflow` ARE available; `sortBy` on a composite
+  orders *within* a group when a query supplies fewer values than the lookup
+  declares, not across the whole result.
+- **Record-only.** The schema's `allowedSurfaces` must be omitted or exactly
+  `[record]` — the platform's composite index has no document/user/entity reader
+  yet.
+
 ### Reference fields — typed links between record types
 
 A `reference` field is a foreign key to another record. It needs **both** the

package/CHANGELOG.md

@@ -3,6 +3,155 @@
 All notable changes to `@vectros-ai/cli` are documented here.
 This project adheres to [Semantic Versioning](https://semver.org).
 
+## 0.14.0
+
+### Security
+
+- **`bootstrap` no longer stores your minted `ssk_*` in plaintext.** The key
+  goes to this machine's OS credential store (or an encrypted file where none
+  is available); your MCP client config references it by alias only
+  (`VECTROS_KEYRING_ALIAS`), never the raw secret. **Breaking:** a config
+  merged by an older CLI keeps working, but a fresh `bootstrap` run now
+  produces the alias-only shape — if you scripted against the printed
+  snippet's `VECTROS_API_KEY` field, it's `VECTROS_KEYRING_ALIAS` now.
+
+- **`--print` is renamed `--no-merge`, with no back-compat alias.** It was
+  never a dry run — it always applies for real and only changes where the
+  result goes. It still applies; it just skips writing your client's config
+  file. For a true preview, use `blueprint plan`.
+
+### Added
+
+- **`key issue --to-keyring` and `key rotate --to-keyring` store the minted secret
+  instead of printing it.** Until now the mint verbs could only *emit* a key, so on
+  a desktop the only place to put it was the MCP client's config file, in plaintext.
+  `--to-keyring` writes it to this machine's OS credential store where one is in use,
+  and to the encrypted file under `~/.vectros/secrets` otherwise — telling you which
+  of the two took it either way, because only one of them is login-gated. The key is
+  never printed to a terminal, a pipe or a transcript. Anything that resolves a
+  credential through `vectros keyring show --format raw` — the MCP server included
+  — then reads it with no `VECTROS_API_KEY` set anywhere.
+
+  `--alias <name>` names the entry (default: the context id) and `--no-activate`
+  stores it without making it the active identity. Emitting stays the **default**:
+  it is the right behaviour for a headless server, where a secrets manager
+  distributes the key and nothing should persist it locally. The two destinations
+  are mutually exclusive — `--to-keyring` with `--format raw|env|json` is rejected
+  before anything is minted, rather than storing the key and printing it anyway.
+
+  `rotate --to-keyring` proves the store will accept a write *before* it revokes
+  the old key, so a machine that cannot hold a secret fails with your existing
+  credential intact.
+
+### Fixed
+
+- **`bootstrap --plan` no longer claims `HYBRID` for a schema that declares no
+  `indexMode`.** The plan rendered an absent mode as `HYBRID`, but nothing
+  substitutes that default — the value is forwarded untouched, and the platform
+  then resolves an absent mode to `NONE` (store-only, never searchable) on a record
+  schema, and rejects a document schema that declares none. So the plan promised a
+  searchable type and the apply produced a store-only one, or previewed a request
+  the API would refuse. The plan now names the real outcome in both cases.
+
+### Changed
+
+- **A blueprint may now declare `indexMode: NONE`** (store-only: kept and looked up, never
+  searchable). The mode has always been accepted by the platform, and `bootstrap`/`validate`/`plan`
+  rejected it earlier than that — structural validation runs against this CLI's own bundled copy of
+  the blueprint format, which predated the value. That copy now carries it, so a blueprint declaring
+  `NONE` validates and applies. This governs blueprints loaded **from a file** as much as bundled
+  ones: both funnel through the same structural parse.
+
+- **`blueprint init` scaffold and `AUTHORING.md`** document the full `indexMode` set including
+  `NONE`, and warn that omitting the field does not mean `HYBRID` — a record schema with no mode of
+  its own resolves to `NONE`, and a document schema with none is rejected.
+
+## 0.13.0
+
+### Added
+
+- **`access explain` shows the row for "this record IS the identity you asked about".** A clause
+  bounding a namespace that belongs to an identity entity — a value the platform derives from the
+  entity's own id rather than one stored on the record — previously produced no matrix row for it at
+  all, because the matrix only built rows from values a clause spelled out literally. The matrix now
+  always carries that row, so a clause confining a credential to its own entity can be checked the same
+  way as every other ownership shape.
+- **`access explain`'s grant matrix shows exactly which record types a row reaches, not only whether
+  it's granted.** A new "record types" column (`recordTypes` in `--json` output) names the types a
+  row's granting clause(s) actually cover — every type, a specific list, or none. Previously an
+  ownership-unscoped but type-restricted clause (a curated shared-content role, for example) rendered as
+  a plain "granted", which read as reaching every record type sharing that ownership shape, including
+  ones the clause never actually named.
+- **`access explain` understands the placement matchers.** `${{ any }}` renders as `any` and matches
+  any value present in that dimension — deliberately *not* a record with no value there, since it does
+  not subsume the `null` sentinel (`[${{ any }}]` and `[${{ any }}, null]` are different grants).
+  `${{ under.self.* }}` renders as `under-self`; deciding it requires the parent edge of every
+  candidate value, which only the server has, so the matrix reports it as undecidable rather than
+  guessing. Previously both were compared as literal strings, so a clause using either was shown as
+  matching only a record whose owner value was the placeholder text itself.
+- **New lint rule `datascope-unknown-placeholder` (error).** A `${{ … }}` value in a `dataScope` that
+  is not one of the platform's placeholders is now caught offline, with the correct spellings in the
+  message, instead of surfacing as a `400` at `apply`. Blueprint-level tokens (`${{ identities.* }}`,
+  `${{ inputs.* }}`, …) are substituted before the value reaches the platform and are not flagged.
+- **A blueprint schema can now declare a composite (conjunctive) lookup** — `lookupFields: [{ fieldNames:
+  ['status', 'area'] }]` matches on several fields at once ("every record where `status` is `open` **and**
+  `area` is `billing`"), 2-3 fields, exact and complete, in the declared field order. `blueprint validate`
+  now catches every leg-shape mistake the platform would otherwise 400 on mid-`bootstrap`: an undeclared
+  leg (naming the exact leg, not just the first), a repeated leg, a leg that's `array`/`object`-typed or a
+  many-cardinality reference, a leg that's separately declared `rangeEnabled`, and a leg used as its own
+  `sortBy` target. `bootstrap`/`blueprint-test apply` forward a composite to the partner API unchanged, and
+  the approval plan (`bootstrap`'s "Apply this plan?" preview) now renders one as `(status+area)` rather
+  than dropping it from the lookup list. `unique`/`rangeEnabled` aren't available on a composite; `sortBy`
+  and `allowOverflow` are. No bundled blueprint declares one yet — adopting the shape in the bundled
+  library is a separate, deliberate content decision.
+
+### Changed
+
+- **`--scope` now validates the value locally, on every command that takes it** — `join`,
+  `access grant` and `identity create`. A scope value must be 1-128 characters, starting with a letter
+  or digit and otherwise containing only letters, digits, `_` and `-` — the grammar the API enforces,
+  because a scope value becomes part of a storage key. `--scope org:a:b:c` previously passed a
+  colon-bearing value straight through; it now fails immediately, naming the offending value, instead
+  of returning a server error later in the call.
+- **`access grant --identity-overrides` validates its values too.** The JSON form wins on key
+  conflicts with `--scope`, so a value rejected on one flag could previously be reinstated by the other
+  in the same command. Both are now checked after the merge.
+- **Dependency maintenance** — repinned the bundled `@vectros-ai/sdk` to `0.38.0` (composite/conjunctive
+  record lookups — a schema can now be looked up by 2-3 fields matched together in one clause, not just
+  one — plus the placement matchers `${{ any }}` / `${{ under.self.* }}`, the `"*"` dimension wildcard in
+  `data_scope`, and sealed pagination cursors) and the bundled `@vectros-ai/blueprints` to `0.10.0` (the
+  composite-lookup authoring format above). The CLI bundles both into its published binary, so this is a
+  rebuild against their current versions.
+
+### Fixed
+
+- **`access explain` no longer reports a fully-permissive scope as granting nothing.** A clause using
+  the dimension wildcard — `data_scope: {"*": [...]}`, which grants over every dimension the clause
+  does not name explicitly — was read as naming an *unrecognized* dimension, and an unrecognized
+  dimension kills a whole clause. The most permissive shape there is therefore rendered as an empty
+  matrix. `*` is now recognized, and it is applied only to the dimensions a record actually carries,
+  with an explicit entry for a dimension always taking precedence over it.
+- **`access explain` now says plainly that its "granted?" and "actions" columns model reading a record,
+  not writing one.** A clause that doesn't mention an ownership dimension no longer authorizes placing a
+  value there, but it never narrowed reads to begin with — so a create/update verb next to a row is not
+  confirmation that a write with that row's exact ownership shape will succeed. The command's output
+  now says so directly instead of leaving it implicit.
+- **`access explain` recognizes a `${{ self.scope.<ns> }}` / `${{ under.self.scope.<ns> }}` placeholder
+  for every namespace the platform accepts, not just letters and dots.** A namespace containing a digit,
+  `_`, or `-` (`${{ self.scope.eng_team }}`) previously fell through to being matched as an opaque
+  literal string instead of resolving to the caller, silently under-reporting that clause's grant.
+- **Corrected the `sortBy` guidance in `AUTHORING.md`.** It carried a "trap"
+  warning that sorting an equality lookup by an **optional** payload field
+  "silently drops records that don't have it." That was never accurate — an
+  equality lookup resolves on the partition key, and `sortBy` only orders within
+  it — and records with no value for the sorted field now take their own ordered
+  position ahead of the rest, and are never inside a `sortFrom`/`sortTo` window.
+  That ordering applies to records written from this platform release onward;
+  earlier records take their new position once they are next updated.
+  The section now also names what `sortBy` really locks: the sorted field's
+  declared `fieldType` is migration-locked alongside `sortBy` itself, and an
+  `array`/`object` field is rejected as a `sortBy` target.
+
 ## 0.12.0
 
 ### Added

package/README.md

@@ -115,7 +115,9 @@ The app-context is intentionally **not** deleted (it's idempotent and reused).
 A machine can hold several Vectros identities (one per context or principal).
 The keyring stores them as named entries plus one **active** pointer, so you can
 switch between them without re-issuing keys. `vectros join <context>` adds an
-entry and activates it; `vectros switch <alias>` flips the active one.
+entry and activates it; `vectros key issue`/`key rotate` add one when passed
+`--to-keyring` (which stores the new secret instead of printing it); `vectros switch
+<alias>` flips the active one.
 
 ```bash
 vectros keyring list                 # the entries; * marks the active one