@vectros-ai/cli 0.12.0 → 0.13.0

package/AUTHORING.md

@@ -134,7 +134,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 +193,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 +210,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,92 @@
 All notable changes to `@vectros-ai/cli` are documented here.
 This project adheres to [Semantic Versioning](https://semver.org).
 
+## 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