objectstack-ai
diff --git a/‎.changeset/alias-citations-two-roles-sweep.md‎
Lines changed: 14 additions & 0 deletions b/‎.changeset/alias-citations-two-roles-sweep.md‎
Lines changed: 14 additions & 0 deletions
diff --git a/‎packages/objectql/src/validation/record-validator.ts‎
Lines changed: 11 additions & 3 deletions b/‎packages/objectql/src/validation/record-validator.ts‎
Lines changed: 11 additions & 3 deletions
diff --git a/‎packages/spec/src/data/default-value-shape.test.ts‎
Lines changed: 8 additions & 3 deletions b/‎packages/spec/src/data/default-value-shape.test.ts‎
Lines changed: 8 additions & 3 deletions
diff --git a/‎packages/spec/src/data/default-value-shape.ts‎
Lines changed: 21 additions & 4 deletions b/‎packages/spec/src/data/default-value-shape.ts‎
Lines changed: 21 additions & 4 deletions
diff --git a/‎packages/spec/src/data/driver/turso.test.ts‎
Lines changed: 37 additions & 0 deletions b/‎packages/spec/src/data/driver/turso.test.ts‎
Lines changed: 37 additions & 0 deletions
diff --git a/‎packages/spec/src/data/driver/turso.zod.ts‎
Lines changed: 11 additions & 1 deletion b/‎packages/spec/src/data/driver/turso.zod.ts‎
Lines changed: 11 additions & 1 deletion
diff --git a/‎packages/spec/src/data/field-value.test.ts‎
Lines changed: 68 additions & 3 deletions b/‎packages/spec/src/data/field-value.test.ts‎
Lines changed: 68 additions & 3 deletions
diff --git a/‎packages/spec/src/data/field-value.zod.ts‎
Lines changed: 18 additions & 3 deletions b/‎packages/spec/src/data/field-value.zod.ts‎
Lines changed: 18 additions & 3 deletions
@@ -0,0 +1,14 @@
+---
+'@objectstack/spec': patch
+'@objectstack/objectql': patch
+---
+
+Correct six `edit distance cannot reach` citations that are measurably false, and pin the role each alias entry actually plays.
+
+`aliases` has two jobs, not one: filling a gap the distance fallback leaves empty, and overruling a hit the fallback reaches and gets wrong. The lookup is `aliases[aliasProbe(key)] ?? findClosestMatches(key, knownKeys, budget, 1)[0]` — the table is consulted first and wins outright — and the budget is `Math.max(2, Math.floor(key.length / 3))`. A sentence saying distance "cannot reach" the cited case denies the second job, and in three places the cited case is itself an example of it.
+
+- **`latitude` → `lat` is an OVERRULE, not a gap** (`data/field-value.zod.ts`, `data/default-value-shape.ts`, `data/field-value.test.ts`, `data/default-value-shape.test.ts`, objectql `validation/record-validator.ts`). `latitude` is 8 characters, so the budget is 2; `lat` is 5 edits away and out of reach, but the declared `altitude` is exactly 2 — so without the curated entry the bare fallback answers `latitude` → `altitude` and points an author who wrote a GPS latitude at the elevation member. Four docblocks cited this pair as proof that aliases exist only where distance reaches nothing.
+- **`postal_code` → `postalCode` never involved an alias at all** (`data/default-value-shape.ts`). Scoring folds case and separators on both sides, so it is 1 edit against a budget of 3 — the worked example rendered in that docblock is the fallback's own answer, not the `AddressValueSchema` table's.
+- **`uri` → `url` is reachable and agreeing** (`data/driver/turso.zod.ts`). The block was headed "the spellings edit distance cannot reach"; that is true of five of its six rows and false of `uri`, which is 1 edit from `url` against a budget of 2. The row is a pin on an answer the fallback already gets right, not a gap-filler.
+
+Prose plus new pins. No alias is added or removed, no schema, key list, strictness, suggestion or error message changes: `Clause-②: no`. The three roles are now asserted — `longitude` (gap), `latitude` (overrule, with the negative half), `altitud` (a plain typo still riding the fallback) in `data/field-value.test.ts`, and `dsn` (gap) beside `uri` (reachable) in `data/driver/turso.test.ts`.
@@ -555,9 +555,17 @@ export function coerceBooleanFields<T extends Record<string, unknown>>(
  *     [1] invalid_type       lng   Invalid input: expected number, received undefined
  *     [2] unrecognized_keys        ... Did you mean `latitude` -> `lat`, `longitude` -> `lng`? ...
  *
- * The rename IS the prescription, and edit distance cannot reach it
- * (`latitude` -> `lat`), which is exactly why `LocationValueSchema` curates an
- * `aliases` map. Reading positionally builds that hint and then discards it,
+ * The rename IS the prescription, and the distance fallback will not hand it
+ * over: `latitude` -> `lat` is 5 edits against a budget of
+ * `Math.max(2, Math.floor(key.length / 3))` = 2 (spec `shared/suggestions.zod.ts`).
+ * What the fallback hands over instead is not silence — `altitude` is a
+ * declared member of the same shape, 2 edits away and inside the budget — so
+ * `LocationValueSchema`'s `aliases` entry is OVERRULING a confident wrong
+ * answer rather than filling a gap: the lookup is
+ * `aliases[aliasProbe(key)] ?? findClosestMatches(…)`, table first and winning
+ * outright. That is the entry's real job here, and spec's
+ * `data/field-value.test.ts` pins both halves of it. Reading positionally
+ * builds that hint and then discards it,
  * leaving an operator running `os migrate value-shapes` to derive the rename
  * themselves while the identically-shaped `address` case is handed it.
  *
 
@@ -138,9 +138,14 @@ describe('#7127 checkLiteralDefaultValue — the shared stored-form literal chec
     expect(v.detail).toContain('`latitude` \u2192 `lat`');
     expect(v.detail).toContain('`longitude` \u2192 `lng`');
     expect(v.detail).not.toContain('expected number, received undefined');
-    // Edit distance cannot reach `latitude` -> `lat`; the curated `aliases`
-    // map is the only thing that can, which is why discarding it cost the
-    // author the whole prescription.
+    // `latitude` -> `lat` is 5 edits against a budget of 2, so the curated
+    // `aliases` map is the only thing that produces THIS rename. Note what the
+    // fallback does instead of nothing: `altitude` is a declared member 2
+    // edits away, so without the entry the author would be pointed at the
+    // elevation member — the alias overrules a wrong answer here rather than
+    // filling a silent gap (`field-value.test.ts` pins both halves). Either
+    // way the prescription rides the unrecognized-keys issue, which is why
+    // discarding it cost the author the whole thing.
   });
 
   it('#16077 prefers the rename over a WRONG-TYPED-member error (address)', () => {
 
@@ -119,10 +119,27 @@ export interface LiteralDefaultValueVerdict {
  *     [0] invalid_type          street   Invalid input: expected string, received number
  *     [1] unrecognized_keys              ... Did you mean `postal_code` -> `postalCode`? ...
  *
- * The rename IS the prescription, and edit distance cannot reach it
- * (`latitude` -> `lat`), which is exactly why `LocationValueSchema` and
- * `AddressValueSchema` curate an `aliases` map. Reading positionally built that
- * hint and threw it away, handing the author a missing-member type error about
+ * The rename IS the prescription. Which channel produced it depends on the
+ * key, and the two cases this function is pinned against are one of each — so
+ * "the curated `aliases` map is what makes the rename possible" is true of only
+ * half of them. The fallback budget is `Math.max(2, Math.floor(key.length / 3))`
+ * (`shared/suggestions.zod.ts`), and the lookup is
+ * `aliases[aliasProbe(key)] ?? findClosestMatches(key, knownKeys, budget, 1)[0]`
+ * — the table is consulted first and wins outright.
+ *
+ *  - `postal_code` -> `postalCode`, the example rendered above, is the
+ *    FALLBACK's own answer: scoring folds case and separators on both sides, so
+ *    it is 1 edit against a budget of 3, and `AddressValueSchema`'s alias table
+ *    never sees the key.
+ *  - `latitude` -> `lat` is 5 edits against a budget of 2 and does come from
+ *    `LocationValueSchema`'s curated entry — but not because the fallback is
+ *    silent. `altitude` is a declared member 2 edits away, inside the budget,
+ *    so the bare fallback answers `latitude` -> `altitude` and this alias
+ *    OVERRULES a confident wrong answer. That is an alias's second job, and
+ *    `field-value.test.ts` pins both halves of it.
+ *
+ * Reading positionally built that hint and threw it away, handing the author a
+ * missing-member type error about
  * a member they never wrote — and which of the two they got depended on whether
  * some unrelated member happened to also be wrong, which nobody chose and
  * nobody can see.
 
@@ -11,6 +11,7 @@
 
 import { describe, expect, it } from 'vitest';
 
+import { findClosestMatches } from '../../shared/suggestions.zod';
 import { DatasourceSchema } from '../datasource.zod';
 import { validateDriverConfig } from './config-registry.zod';
 import { TursoConfigSchema, TursoDriverSpec } from './turso.zod';
@@ -70,6 +71,42 @@ describe('TursoConfigSchema', () => {
     expect(result.success).toBe(false);
     expect(JSON.stringify(result.error?.issues)).toContain('url');
   });
+
+  // The alias block above this shape's keys used to be headed "the spellings
+  // edit distance cannot reach", which is true of five of its six rows and
+  // false of `uri`. The two roles are pinned separately because they fail
+  // differently: drop a GAP row and the author gets silence, drop the `uri`
+  // row and nothing observable changes today — its value is that it keeps
+  // answering `url` if this shape ever gains a key within 2 of `uri`.
+  describe('the alias table, by role', () => {
+    const rename = (key: string, value: unknown) => {
+      const result = TursoConfigSchema.safeParse({ url: 'libsql://x.turso.io', [key]: value });
+      expect(result.success).toBe(false);
+      const issue = result.error!.issues.find((i) => i.code === 'unrecognized_keys');
+      expect(issue, 'the refusal carries an unrecognized-keys issue').toBeDefined();
+      return issue!.message;
+    };
+
+    it('`dsn` is the GAP case — 3 edits from `url` against a budget of 2', () => {
+      // Nothing declared on this shape is within 2 of `dsn`, so without the
+      // row the refusal names the key and stops.
+      expect(rename('dsn', 'libsql://x.turso.io')).toContain('`dsn` → `url`');
+    });
+
+    it('`uri` is NOT — the bare fallback already reaches `url` at distance 1', () => {
+      // `uri` is 3 characters, so the budget is `Math.max(2, floor(3 / 3))` = 2
+      // and `uri`/`url` differ by exactly 1. The row and the fallback agree, so
+      // this message is what an author sees either way — which is the whole
+      // point: the entry is not what makes the suggestion possible.
+      //
+      // `shape` is a conservative SUPERSET of the candidate list the error map
+      // spends (that one drops the `authToken`/`timeout` tombstones via
+      // `acceptsNothing`); extra candidates can only crowd `url` out, never
+      // help it, so a pass here holds for the real list too.
+      expect(findClosestMatches('uri', Object.keys(TursoConfigSchema.shape), 2, 1)).toEqual(['url']);
+      expect(rename('uri', 'libsql://x.turso.io')).toContain('`uri` → `url`');
+    });
+  });
 });
 
 describe('turso is a known driver to the config registry now (#6345)', () => {
 
@@ -80,7 +80,17 @@ export type TursoTransportMode = z.input<typeof TursoTransportModeSchema>;
 export const TursoConfigSchema = lazySchema(() => strictObject(
   {
     surface: "this turso datasource's config",
-    // Semantic near-misses only — the spellings edit distance cannot reach.
+    // Semantic near-misses — a different WORD for a declared key. FIVE of the
+    // six are the unreachable case: `connectionstring`, `dsn`, `database`,
+    // `databaseurl` and `syncinterval` all score past their budget against
+    // every declared key, so without the entry the author gets no suggestion
+    // at all. `uri` is NOT, and the entry is worth keeping for the opposite
+    // reason: the budget is `Math.max(2, Math.floor(key.length / 3))`
+    // (`shared/suggestions.zod.ts`), so a 3-character key gets 2, and `uri`
+    // differs from `url` by 1 — the bare fallback already answers `url`. That
+    // row is a PIN on an answer the fallback happens to get right, not a
+    // gap-filler, and it keeps answering `url` if this shape ever gains a key
+    // within 2 of `uri`. `turso.test.ts` pins the distinction.
     // Case and underscore variants of a DECLARED key (`encryption_key`,
     // `sync_url`) are deliberately absent: the unknown-key probe already
     // normalizes those onto the declared name, so entries for them would be
 
@@ -30,13 +30,37 @@ import {
   valueSchemaFor,
   referenceTargetOf,
   referenceCarrierOf,
+  LocationValueSchema,
 } from './field-value.zod';
+import { findClosestMatches } from '../shared/suggestions.zod';
 
 const ok = (def: Parameters<typeof valueSchemaFor>[0], v: unknown, form?: 'stored' | 'expanded') =>
   expect(valueSchemaFor(def, form).safeParse(v).success).toBe(true);
 const bad = (def: Parameters<typeof valueSchemaFor>[0], v: unknown, form?: 'stored' | 'expanded') =>
   expect(valueSchemaFor(def, form).safeParse(v).success).toBe(false);
 
+/**
+ * The candidate list the `location` error map actually spends its budget
+ * against, read off the schema rather than transcribed beside it — a second
+ * copy of a key list is the shape `shared/alias-integrity.test.ts` exists to
+ * refuse. No member of this shape is a tombstone, so every declared key is a
+ * candidate.
+ */
+const LOCATION_KEYS: readonly string[] = Object.keys(LocationValueSchema.shape);
+
+/** The fallback budget, verbatim from `strictUnknownKeyError`. */
+const budgetFor = (key: string) => Math.max(2, Math.floor(key.length / 3));
+
+/** The `unrecognized_keys` issue a stored `location` value rejection carries. */
+const firstLocationIssue = (value: Record<string, unknown>) => {
+  const r = valueSchemaFor({ type: 'location' }, 'stored').safeParse(value);
+  expect(r.success).toBe(false);
+  const issues = (r as { error: { issues: Array<{ code: string; message: string }> } }).error.issues;
+  const issue = issues.find((i) => i.code === 'unrecognized_keys');
+  expect(issue, 'the rejection carries an unrecognized-keys issue').toBeDefined();
+  return issue!;
+};
+
 describe('semantic type classes', () => {
   it('every class member is a declared FieldType', () => {
     const all = new Set<string>(FieldType.options);
@@ -388,9 +412,11 @@ describe('valueSchemaFor — stored form (field-zoo reality)', () => {
     expect(geo.message).toContain('this location value');
     expect(geo.message).not.toMatch(/#\d+/);
 
-    // The retired spec-only spelling carries its rename (an alias — edit
-    // distance cannot reach `latitude` → `lat`). It is ALSO a missing-pair
-    // rejection; the unrecognized-keys issue is the one that names the fix.
+    // The retired spec-only spelling carries its rename from the curated
+    // alias, not from the distance fallback — and for `latitude` that alias is
+    // OVERRULING the fallback rather than filling a gap (pinned in the next
+    // test). It is ALSO a missing-pair rejection; the unrecognized-keys issue
+    // is the one that names the fix.
     const retired = valueSchemaFor({ type: 'location' }, 'stored').safeParse({ latitude: 1, longitude: 2 });
     expect(retired.success).toBe(false);
     const unknown = (retired as { error: { issues: Array<{ code: string; message: string }> } }).error.issues
@@ -412,4 +438,43 @@ describe('valueSchemaFor — stored form (field-zoo reality)', () => {
     ok({ type: 'formula' }, 31.5);
     ok({ type: 'autonumber' }, 'INV-0001');
   });
+
+  // An alias entry has TWO jobs, not one, and `LocationValueSchema` ships one
+  // of each — which is why three docblocks around this shape used to cite
+  // `latitude` → `lat` as proof that aliases exist only where distance reaches
+  // nothing. The fallback budget is `Math.max(2, Math.floor(key.length / 3))`
+  // (`shared/suggestions.zod.ts`), and the lookup is
+  // `aliases[aliasProbe(key)] ?? findClosestMatches(key, knownKeys, budget, 1)[0]`
+  // — table first, winning outright.
+  describe('the `location` alias entries, one per role', () => {
+    it('`longitude` fills a GAP — no declared member is within budget', () => {
+      // 9 characters, so the budget is 3; `lng` is 6 edits away and nothing
+      // else on the shape is closer. Drop the entry and the author gets no
+      // suggestion at all, which is the role the prose always described.
+      expect(findClosestMatches('longitude', LOCATION_KEYS, budgetFor('longitude'), 1)).toEqual([]);
+      const issue = firstLocationIssue({ lat: 1, lng: 2, longitude: 3 });
+      expect(issue.message).toContain('`longitude` → `lng`');
+    });
+
+    it('`latitude` OVERRULES a live wrong answer — the bare fallback reaches `altitude`', () => {
+      // 8 characters, so the budget is 2. `lat` is 5 edits away and out of
+      // reach, but the declared `altitude` is exactly 2 — inside the budget —
+      // so the fallback is not silent here, it is WRONG. Without the entry the
+      // refusal would read ``Did you mean `latitude` → `altitude`?`` and point
+      // an author who wrote a GPS latitude at the elevation member. That is
+      // why the negative half is asserted and not only the positive one.
+      expect(findClosestMatches('latitude', LOCATION_KEYS, budgetFor('latitude'), 1)).toEqual(['altitude']);
+      const issue = firstLocationIssue({ lat: 1, lng: 2, latitude: 3 });
+      expect(issue.message, 'the curated target is offered').toContain('`latitude` → `lat`');
+      expect(issue.message, 'the reachable wrong answer is not').not.toContain('`latitude` → `altitude`');
+    });
+
+    it('a plain typo still rides the fallback — the table is not in its way', () => {
+      // The control that keeps the two assertions above from passing against a
+      // fallback that answers nothing at all: `altitud` is one edit from the
+      // declared `altitude` and no alias mentions it.
+      const issue = firstLocationIssue({ lat: 1, lng: 2, altitud: 3 });
+      expect(issue.message).toContain('`altitud` → `altitude`');
+    });
+  });
 });
@@ -398,9 +398,24 @@ export const LocationValueSchema = lazySchema(() => strictObject(
     history: 'Until this shape was closed, an undeclared key on a location value was silently '
       + 'dropped — the value parsed green with the key gone, so the mistake surfaced only as a '
       + 'blank on screen.',
-    // The retired spec-only spelling (see the module header). Edit distance
-    // cannot reach `latitude` → `lat`; the value contract has refused the pair
-    // since ADR-0104 D1, so the rename is the one an author actually needs.
+    // The retired spec-only spelling (see the module header). The two entries
+    // play DIFFERENT roles and neither is optional. The fallback budget is
+    // `Math.max(2, Math.floor(key.length / 3))` (`shared/suggestions.zod.ts`).
+    //
+    //  - `longitude` → `lng` is the unreachable case: 6 edits against a budget
+    //    of 3, and no other declared member is closer, so without this entry
+    //    the author gets no suggestion at all.
+    //  - `latitude` → `lat` is 5 edits against a budget of 2 — also past the
+    //    budget — but the fallback does NOT stay silent for it: `altitude` is
+    //    a declared member 2 edits away, inside the budget, so the bare
+    //    fallback answers `latitude` → `altitude`. This entry OVERRULES a
+    //    confident wrong answer rather than filling a gap, which is the other
+    //    job an alias does: `aliases[aliasProbe(key)] ?? findClosestMatches(…)`
+    //    consults the table first and wins outright.
+    //
+    // The value contract has refused the pair since ADR-0104 D1, so the rename
+    // is the one an author actually needs. `field-value.test.ts` pins both
+    // roles, including the negative half for `latitude`.
     aliases: { latitude: 'lat', longitude: 'lng' },
   },
   {