@openparachute/vault 0.7.0-rc.5 → 0.7.0-rc.6

package/core/src/schema-defaults.ts

@@ -60,6 +60,20 @@ export interface SchemaField {
   type?: "string" | "number" | "integer" | "boolean" | "array" | "object";
   enum?: string[];
   description?: string;
+  /**
+   * Mirrors `TagFieldSchema.indexed` (core/src/tag-schemas.ts) — this field
+   * has a generated column + B-tree index maintained on `notes` (see
+   * core/src/indexed-fields.ts). Parsed here (not just there) because
+   * `validateNote` uses it: an indexed field is a QUERY CONTRACT, not just a
+   * storage hint, so a `type_mismatch` on an indexed field is always
+   * enforced (`strict: true` on that ONE warning) regardless of this field's
+   * own `strict` flag (vault#553 Decision A). Every other constraint
+   * (enum/required/cardinality) on an indexed field stays governed by
+   * `strict` as before — only the TYPE contract is unconditional, because
+   * that's the one a type-mismatched write can silently poison range
+   * queries with (SQLite's TEXT-sorts-above-INTEGER affinity ordering).
+   */
+  indexed?: boolean;
   /**
    * Strict enforcement opt-in (vault#299, Part A). Default `false` — when
    * unset/false, ALL constraints on this field are advisory: violations
@@ -169,6 +183,7 @@ function parseFieldsJson(raw: string | null): Record<string, SchemaField> {
     if (typeof f.type === "string") field.type = f.type as SchemaField["type"];
     if (Array.isArray(f.enum)) field.enum = f.enum.filter((x): x is string => typeof x === "string");
     if (typeof f.description === "string") field.description = f.description;
+    if (f.indexed === true) field.indexed = true;
     if (f.strict === true) field.strict = true;
     if (f.required === true) field.required = true;
     if (f.cardinality === "one" || f.cardinality === "many") field.cardinality = f.cardinality;
@@ -319,6 +334,20 @@ function stringArraysEqual(a: string[] | undefined, b: string[] | undefined): bo
   return true;
 }
 
+/**
+ * Human-readable JSON-shape name for a value, used to name the "got" side of
+ * a `type_mismatch` message (vault#553 — "message names field + expected
+ * type + got type"). Distinct from SQLite's `json_type()` vocabulary
+ * (integer/real/true/false/text/...) — this is the JSON-Schema-ish vocabulary
+ * `SchemaField.type` already uses, so the message reads as "expected X, got
+ * Y" in the SAME words the schema declares.
+ */
+function jsonTypeOf(value: unknown): string {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  return typeof value; // "string" | "number" | "boolean" | "object" | ...
+}
+
 function valueMatchesType(value: unknown, type: SchemaField["type"]): boolean {
   if (type === undefined) return true;
   switch (type) {
@@ -357,11 +386,15 @@ function valueMatchesType(value: unknown, type: SchemaField["type"]): boolean {
  *   → `cardinality_mismatch`
  *
  * Every violation carries `strict: true` iff its field declared `strict:true`
- * (vault#299). The list itself is the SAME whether or not a field is strict —
- * the difference is only the per-warning `strict` flag, which the write path
- * uses to decide block-vs-warn. Under `strict:false` this is byte-identical to
- * the historical advisory behavior PLUS the new `required`/`cardinality`
- * advisory reasons (which fire for any field declaring those, strict or not).
+ * (vault#299) — EXCEPT a `type_mismatch` on an `indexed: true` field, which is
+ * ALWAYS `strict: true` regardless of the field's own `strict` setting
+ * (vault#553 Decision A — an indexed field's type is a query contract, not
+ * just guidance). The list itself is the SAME whether or not a field is
+ * strict — the difference is only the per-warning `strict` flag, which the
+ * write path uses to decide block-vs-warn. Under `strict:false` (and
+ * `indexed:false`) this is byte-identical to the historical advisory
+ * behavior PLUS the new `required`/`cardinality` advisory reasons (which
+ * fire for any field declaring those, strict or not).
  *
  * Fields not declared by any ancestor's schema are ignored entirely.
  */
@@ -397,12 +430,20 @@ export function validateNote(
     if (absent) continue;
 
     if (spec.type && !valueMatchesType(value, spec.type)) {
+      // Decision A (vault#553): an INDEXED field's type is a query
+      // contract — a type-mismatched write poisons range-query ordering
+      // (SQLite's TEXT-sorts-above-INTEGER affinity) regardless of whether
+      // this field opted into `strict`. Force `strict: true` on THIS
+      // warning alone when the field is indexed; every other constraint
+      // (enum/required/cardinality) stays governed by `spec.strict` as
+      // before.
+      const indexedTypeStrict = spec.indexed === true;
       warnings.push({
         field: fieldName,
         schema: sourceTag,
         reason: "type_mismatch",
-        message: `'${fieldName}' should be ${spec.type} (tag '${sourceTag}')`,
-        ...strictFlag,
+        message: `'${fieldName}' should be ${spec.type} (tag '${sourceTag}'), got ${jsonTypeOf(value)}${indexedTypeStrict ? " — indexed fields reject type-mismatched writes (vault#553)" : ""}`,
+        ...(strictFlag.strict || indexedTypeStrict ? { strict: true } : {}),
       });
     }
 

package/core/src/schema.ts

@@ -1,9 +1,10 @@
 import { Database } from "bun:sqlite";
 import { normalizePath } from "./paths.js";
-import { rebuildIndexes } from "./indexed-fields.js";
+import { rebuildIndexes, listIndexedFields } from "./indexed-fields.js";
+import { findMixedTypeIndexedFieldNotes } from "./doctor.js";
 import { transaction } from "./txn.js";
 
-export const SCHEMA_VERSION = 23;
+export const SCHEMA_VERSION = 24;
 
 export const SCHEMA_SQL = `
 -- Notes: the universal record.
@@ -502,6 +503,10 @@ export function initSchema(db: Database): void {
   // vault#298.
   migrateToV23(db);
 
+  // Migrate v23 → v24: coerce existing typed-index poison where lossless,
+  // leave the rest in place for `doctor` to surface. See vault#553.
+  migrateToV24(db);
+
   // Rebuild any generated columns + indexes declared in indexed_fields.
   // No-op for a fresh vault; idempotent on existing vaults.
   rebuildIndexes(db);
@@ -1187,6 +1192,146 @@ function migrateToV23(db: Database): void {
   }
 }
 
+/** Sentinel returned by {@link coerceIndexedValue} when no lossless conversion exists. */
+const NOT_COERCIBLE = Symbol("not-coercible");
+
+/** Full JSON-number grammar — used to gate string→number coercion to values that round-trip exactly. */
+const JSON_NUMBER_RE = /^-?(0|[1-9]\d*)(\.\d+)?([eE][+-]?\d+)?$/;
+
+/**
+ * Decide the lossless coercion (if any) for a single poisoned indexed-field
+ * value, given `jt` — the SQLite `json_type()` of its CURRENT value (the
+ * SAME vocabulary `doctor`'s `findMixedTypeIndexedFieldNotes` compares
+ * against: "text", "integer", "real", "true", "false", "array", "object")
+ * — and `targetSqliteType`, the field's declared storage class ("INTEGER"
+ * or "TEXT"). Returns the coerced value, or {@link NOT_COERCIBLE} when no
+ * exact round-trip conversion exists — the caller leaves the value
+ * untouched (never deletes or nulls note data).
+ *
+ * Coercible cases (vault#553 Decision D):
+ *   - INTEGER target, TEXT source: a clean numeric string ("5", "5.5",
+ *     "-3") → the JSON number, ONLY when `String(Number(str)) === str`
+ *     (exact round-trip — rejects "5.50", scientific-notation reformats,
+ *     and anything outside safe double precision that wouldn't survive the
+ *     trip). "true"/"false" (exact string match) → the JSON boolean.
+ *   - TEXT target, INTEGER/REAL/boolean source: a number or boolean → its
+ *     JSON string form via `String(value)` — always exact for finite JS
+ *     numbers and booleans within IEEE-754 double precision.
+ * Never coercible: array/object/null values in either direction, or a TEXT
+ * value that isn't a clean number/boolean string (e.g. "four", "5,000").
+ */
+function coerceIndexedValue(
+  value: unknown,
+  jt: string,
+  targetSqliteType: string,
+): unknown | typeof NOT_COERCIBLE {
+  if (targetSqliteType === "INTEGER") {
+    if (jt !== "text" || typeof value !== "string") return NOT_COERCIBLE;
+    if (value === "true") return true;
+    if (value === "false") return false;
+    if (JSON_NUMBER_RE.test(value)) {
+      const n = Number(value);
+      if (Number.isFinite(n) && String(n) === value) return n;
+    }
+    return NOT_COERCIBLE;
+  }
+  if (targetSqliteType === "TEXT") {
+    if ((jt === "true" || jt === "false") && typeof value === "boolean") {
+      return jt; // "true" / "false" — the json_type string IS the target text
+    }
+    if ((jt === "integer" || jt === "real") && typeof value === "number") {
+      const s = String(value);
+      if (Number(s) === value) return s;
+    }
+    return NOT_COERCIBLE;
+  }
+  return NOT_COERCIBLE;
+}
+
+/**
+ * Migrate v23 → v24: typed-index poison coercion (vault#553 Decision D).
+ *
+ * For every declared indexed field (`indexed_fields` — the SSOT from
+ * `core/src/indexed-fields.ts`) and every note whose `metadata.<field>` JSON
+ * type disagrees with the field's declared sqlite storage class — reusing
+ * `doctor`'s `findMixedTypeIndexedFieldNotes` (`core/src/doctor.ts`) as the
+ * DETECTOR, the exact same query that powers the `mixed_type_indexed_field`
+ * finding, so migration and diagnostic can never disagree on what counts as
+ * poisoned:
+ *
+ *   - COERCE where {@link coerceIndexedValue} finds a lossless conversion —
+ *     rewrites `notes.metadata` in place (the generated `meta_<field>`
+ *     column re-derives via `json_extract` automatically; nothing else to
+ *     touch).
+ *   - LEAVE IN PLACE everything else. NEVER DELETE OR NULL NOTE DATA in a
+ *     startup migration — a non-coercible value (e.g. `"hello"` in an
+ *     integer field) stays exactly as written and remains visible via
+ *     `doctor`'s `mixed_type_indexed_field` finding for the operator to
+ *     clean up deliberately.
+ *
+ * Rewrites happen at the JS level — `SELECT metadata` → `JSON.parse` →
+ * mutate the one field → `JSON.stringify` → single-row `UPDATE ... WHERE id
+ * = ?` (two bound params) — rather than SQL `json_set`, so the migration
+ * stays portable to a narrower json1 surface (Cloudflare DO SQLite; flagged
+ * for the wire reviewer to confirm). Detection still uses
+ * `json_extract`/`json_type`/`json_valid`, the same functions the indexed
+ * generated columns and `doctor` already depend on everywhere in this
+ * codebase — not a new cross-runtime risk. One row at a time also means this
+ * never approaches SQLite's bound-parameter ceiling regardless of how many
+ * notes are poisoned (no batched `WHERE id IN (...)`).
+ *
+ * Idempotent: every step is naturally re-runnable (a coerced value now
+ * agrees with the declared type and is never re-detected as a mismatch; a
+ * left-in-place value re-detects identically and is re-skipped identically).
+ * Safe on a vault with zero indexed fields (the field-list guard short-
+ * circuits before any table scan) and safe to run on every boot, matching
+ * the unconditional-migration-function idiom the rest of this file uses.
+ */
+function migrateToV24(db: Database): void {
+  if (!hasTable(db, "notes") || !hasTable(db, "indexed_fields")) return;
+  const fields = listIndexedFields(db);
+  if (fields.length === 0) return;
+
+  let coerced = 0;
+  let left = 0;
+
+  transaction(db, () => {
+    const readStmt = db.prepare("SELECT metadata FROM notes WHERE id = ?");
+    const updateStmt = db.prepare("UPDATE notes SET metadata = ? WHERE id = ?");
+
+    for (const f of fields) {
+      const mismatches = findMixedTypeIndexedFieldNotes(db, f.field, f.sqliteType);
+      for (const { id, jt } of mismatches) {
+        const row = readStmt.get(id) as { metadata: string | null } | null;
+        if (!row?.metadata) continue;
+        let meta: unknown;
+        try {
+          meta = JSON.parse(row.metadata);
+        } catch {
+          continue; // shouldn't happen — findMixedTypeIndexedFieldNotes already filters to json_valid rows
+        }
+        if (!meta || typeof meta !== "object" || Array.isArray(meta)) continue;
+        const obj = meta as Record<string, unknown>;
+        if (!(f.field in obj)) continue;
+        const coercedValue = coerceIndexedValue(obj[f.field], jt, f.sqliteType);
+        if (coercedValue === NOT_COERCIBLE) {
+          left++;
+          continue;
+        }
+        obj[f.field] = coercedValue;
+        updateStmt.run(JSON.stringify(obj), id);
+        coerced++;
+      }
+    }
+  });
+
+  if (coerced > 0 || left > 0) {
+    console.log(
+      `[vault] migrated to schema v24 (vault#553): typed-index poison scan — coerced ${coerced} value(s) to their declared indexed type; left ${left} non-coercible value(s) in place (see \`doctor\`'s mixed_type_indexed_field finding for cleanup).`,
+    );
+  }
+}
+
 function hasTable(db: Database, name: string): boolean {
   const row = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name=?").get(name);
   return !!row;

package/core/src/seed-packs.ts

@@ -468,9 +468,9 @@ update-tag {
   tag: "meeting",
   description: "A meeting with notes",
   fields: {
-    held_on: { type: "string", indexed: true },              // queryable with operators
-    status:  { type: "string", enum: ["scheduled", "done"] }, // first enum value is the default
-    rating:  { type: "integer" }
+    held_on: { type: "string", indexed: true },                                         // queryable with operators
+    status:  { type: "string", enum: ["scheduled", "done"], default: "scheduled" },      // explicit default — declare one to auto-fill
+    rating:  { type: "integer" }                                                        // no default — stays unset until written
   }
 }
 \`\`\`
@@ -490,16 +490,23 @@ A few behaviors worth knowing before you write at scale:
   conflict error (re-read, reconcile, retry). For bulk/scripted writes where
   concurrency is known-safe, pass \`force: true\` to waive the *requirement to
   supply* it. \`append\`/\`prepend\`-only updates are exempt (no-conflict-by-design).
-- **A schema field's default is filled in on write, so it shows up even when you
-  didn't set it.** When a note gets a tag whose schema declares a field, the
-  missing field is back-filled: an \`enum\` field → its **first listed value**, an
-  \`integer\` → \`0\`, a \`boolean\` → \`false\`, a plain string → \`""\`. So a
-  \`rating: { type: "integer" }\` reads as \`0\` on notes nobody rated — that \`0\`
-  is "unset," not "rated zero." Order an \`enum\`'s values so the first is a sane
-  default, and don't read a back-filled \`0\`/\`""\`/\`false\` as a real value.
-- **Validation is advisory, never blocking.** A type/enum mismatch comes back as
-  a \`validation_status\` warning on the write response — the write still lands.
-  Read those warnings and self-correct on the next turn.
+- **A schema field only back-fills when you declare an explicit \`default\`.**
+  When a note gets a tag whose schema declares a field with a \`default\`, an
+  unset field is filled with THAT value. A field with no \`default\` stays
+  genuinely absent — \`query-notes { metadata: { rating: { exists: false } } }\`
+  reliably finds notes that never set \`rating\`. Declare \`default\` on a field
+  only when "unset" and "explicitly set to X" should read the same; leave it
+  off when you need to tell them apart.
+- **Validation is advisory, never blocking — EXCEPT an \`indexed: true\`
+  field's type.** A type/enum mismatch on a non-indexed field (or a
+  non-\`strict\` constraint on any field) comes back as a \`validation_status\`
+  warning and the write still lands — read those warnings and self-correct on
+  the next turn. An \`indexed: true\` field's TYPE is always enforced, though:
+  writing a string into an indexed \`integer\` field is REJECTED with a
+  \`schema_validation\` error, because a bad-typed value would otherwise
+  silently poison range queries (\`gt\`/\`gte\`/\`lt\`/\`lte\`) on that field. Mark a
+  field \`strict: true\` to enforce its OTHER constraints
+  (enum/required/cardinality) the same hard way.
 
 (Full design guide, with copy-paste examples: https://parachute.computer/scripting/)
 

package/core/src/store.ts

@@ -741,6 +741,24 @@ export class BunSqliteStore implements Store {
         // Throws IndexedFieldError on an invalid identifier (e.g. kebab-case).
         indexedFieldOps.validateFieldName(fieldName);
       }
+      // Default-conformance pre-validate (vault#553 Decision B) — mirrors the
+      // indexed-type/name checks above: fail BEFORE any persistence so a bad
+      // `default` never gets written. Runs over EVERY field in the full
+      // (already-merged) `nextFields` map, not just indexed ones — a default
+      // that doesn't match its own field's type/enum is a tag-schema error
+      // regardless of queryability. This is the REST parity path: MCP's
+      // `update-tag` tool ALSO calls `collectTagFieldViolations` before
+      // reaching here (bundling every violation into one `TagFieldConflictError`
+      // — see that function's doc comment), so a conforming MCP call never
+      // trips this; a non-conforming one throws there first. REST has no such
+      // pre-check, so this is REST's only gate — same asymmetry as the
+      // indexed-type/name checks it sits beside.
+      for (const [fieldName, spec] of Object.entries(nextFields ?? {})) {
+        const violation = tagSchemaOps.validateFieldDefault(fieldName, spec);
+        if (violation) {
+          throw new tagSchemaOps.InvalidFieldDefaultError(fieldName, violation.message);
+        }
+      }
     }
 
     // Persist the record + reconcile the indexed-field lifecycle atomically.

package/core/src/tag-schemas.ts

@@ -44,6 +44,25 @@ export interface TagFieldSchema {
   // "one" (scalar, default) or "many" (array). Advisory unless `strict:true`.
   // Distinct from relationship cardinality. vault#299.
   cardinality?: "one" | "many";
+  /**
+   * Explicit backfill value (vault#553 Decision B). When a note gains this
+   * tag and doesn't set the field, `applySchemaDefaults` (core/src/mcp.ts)
+   * writes THIS value onto the note. Undeclared (the default) means the
+   * field stays ABSENT on notes that don't set it — no more implicit
+   * first-enum-value / type-zero-value backfill. This is what makes
+   * `exists:false` trustworthy: "never set" and "explicitly set to the
+   * default" are now distinguishable states.
+   *
+   * Must conform to this field's own `type` (and `enum`, when declared) —
+   * `upsertTagRecord` (core/src/store.ts, the single chokepoint both REST
+   * and MCP funnel through) validates the default BEFORE persisting via
+   * {@link validateFieldDefault}; a non-conforming default is a tag-schema
+   * error (`invalid_field_default` / `TagFieldViolation` reason
+   * `"invalid_default"`), not a silent typo. `undefined` is JSON-serialized
+   * away by `JSON.stringify` — an omitted `default` key round-trips as "not
+   * declared", never as a stored `null`.
+   */
+  default?: unknown;
 }
 
 /**
@@ -147,6 +166,86 @@ export function getTagRecord(db: Database, tag: string): TagRecord | null {
  * for a tag-scoped caller (`scrubParentCycleError` in src/tag-scope.ts),
  * same posture as `TagFieldConflictError`.
  */
+/**
+ * Thrown by `upsertTagRecord` (core/src/store.ts's chokepoint — REST
+ * `PUT /api/tags/:name` and MCP `update-tag` both funnel through it) when a
+ * field's declared `default` (vault#553 Decision B) doesn't conform to that
+ * SAME field's own `type` (or `enum`, when declared). A bad default is a
+ * tag-schema authoring error, not silently-accepted junk that would poison
+ * every note gaining the tag — fail closed, same posture as
+ * `IndexedFieldError` and `ParentCycleError`. `error_type` is stamped
+ * directly (own-field validation leaf, one caller-facing shape) so the
+ * generic MCP domain-error mapping (`src/mcp-http.ts`) and REST's dedicated
+ * catch branch both surface it without a bespoke class-specific mapping.
+ */
+export class InvalidFieldDefaultError extends Error {
+  code = "INVALID_FIELD_DEFAULT" as const;
+  error_type = "invalid_field_default" as const;
+  field: string;
+
+  constructor(field: string, message: string) {
+    super(message);
+    this.name = "InvalidFieldDefaultError";
+    this.field = field;
+  }
+}
+
+/**
+ * Validate that a field's declared `default` (vault#553 Decision B) conforms
+ * to its own `type` and (when declared) `enum`. Returns `null` when the
+ * field has no `default` (the common case) or the default is valid;
+ * otherwise a {@link TagFieldViolation} with `reason: "invalid_default"`.
+ * Pure — never throws; the two callers (the store chokepoint's fail-fast
+ * pre-validate, and {@link collectTagFieldViolations}'s bundled MCP report)
+ * each decide how to surface it.
+ *
+ * Deliberately independent of `schema-defaults.ts`'s `valueMatchesType` (this
+ * module doesn't import that one, and vice versa — no cycle either way) so
+ * the two modules' type vocabularies can drift without cross-coupling; the
+ * rules are kept in lockstep by hand (string/number/integer/boolean/array/
+ * object, the SAME six as `TagFieldSchema.type`'s documented vocabulary).
+ */
+export function validateFieldDefault(field: string, spec: TagFieldSchema): TagFieldViolation | null {
+  if (spec.default === undefined) return null;
+  const value = spec.default;
+  const typeOk = defaultMatchesType(value, spec.type);
+  if (!typeOk) {
+    return {
+      field,
+      reason: "invalid_default",
+      message: `field "${field}" declares default ${JSON.stringify(value)}, which does not match its own type "${spec.type}"`,
+    };
+  }
+  if (spec.enum && spec.enum.length > 0 && typeof value === "string" && !spec.enum.includes(value)) {
+    return {
+      field,
+      reason: "invalid_default",
+      message: `field "${field}" declares default "${value}", which is not one of its own enum values [${spec.enum.join(", ")}]`,
+    };
+  }
+  return null;
+}
+
+/** Same six-type vocabulary as `TagFieldSchema.type`'s doc comment. Unknown/unset types pass (nothing to check against). */
+function defaultMatchesType(value: unknown, type: string): boolean {
+  switch (type) {
+    case "string":
+      return typeof value === "string";
+    case "number":
+      return typeof value === "number" && Number.isFinite(value);
+    case "integer":
+      return typeof value === "number" && Number.isInteger(value);
+    case "boolean":
+      return typeof value === "boolean";
+    case "array":
+      return Array.isArray(value);
+    case "object":
+      return !!value && typeof value === "object" && !Array.isArray(value);
+    default:
+      return true;
+  }
+}
+
 export class ParentCycleError extends Error {
   code = "PARENT_CYCLE" as const;
   error_type = "parent_cycle" as const;
@@ -403,7 +502,12 @@ function jsonOrNull(value: unknown): string | null {
  */
 export interface TagFieldViolation {
   field: string;
-  reason: "type_conflict" | "indexed_flag_conflict" | "unsupported_indexed_type" | "invalid_field_name";
+  reason:
+    | "type_conflict"
+    | "indexed_flag_conflict"
+    | "unsupported_indexed_type"
+    | "invalid_field_name"
+    | "invalid_default";
   message: string;
   /**
    * The conflicting declarer tag — present on the cross-tag reasons
@@ -522,12 +626,17 @@ export function collectCrossTagFieldViolations(
 /**
  * Full field-violation collection: {@link collectCrossTagFieldViolations}
  * PLUS the own-field checks (unsupported type for indexing, invalid
- * identifier). Used by the MCP `update-tag` tool, which — unlike REST — had
- * no prior single-violation status-code contract to preserve for those two
- * checks (its old inline loop threw an unstructured `Error` for them, same
- * as everything else pre-#554); collecting everything here is a strict
+ * identifier, and — vault#553 Decision B — a non-conforming `default`).
+ * Used by the MCP `update-tag` tool, which — unlike REST — had no prior
+ * single-violation status-code contract to preserve for those checks (its
+ * old inline loop threw an unstructured `Error` for them, same as
+ * everything else pre-#554); collecting everything here is a strict
  * improvement. See {@link collectCrossTagFieldViolations}'s doc comment for
- * why REST calls that narrower function directly instead of this one.
+ * why REST calls that narrower function directly instead of this one — REST
+ * gets the SAME `invalid_default` coverage via `store.upsertTagRecord`'s
+ * fail-fast pre-validate (mirrors its indexed-type/name checks), just as a
+ * single-violation `InvalidFieldDefaultError` → 400 rather than a bundled
+ * `TagFieldConflictError` → 422.
  */
 export function collectTagFieldViolations(
   db: Database,
@@ -537,6 +646,12 @@ export function collectTagFieldViolations(
   const violations = collectCrossTagFieldViolations(db, tag, incomingFields);
 
   for (const [fieldName, spec] of Object.entries(incomingFields)) {
+    // Own-field default-conformance check (vault#553 Decision B) — applies
+    // to EVERY field (not just indexed ones); a bad default is a tag-schema
+    // error regardless of whether the field is queryable.
+    const defaultViolation = validateFieldDefault(fieldName, spec);
+    if (defaultViolation) violations.push(defaultViolation);
+
     if (spec.indexed === true) {
       const mapped = mapFieldType(spec.type);
       if (!mapped) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/vault",
-  "version": "0.7.0-rc.5",
+  "version": "0.7.0-rc.6",
   "description": "Agent-native knowledge graph. Notes, tags, links over MCP.",
   "module": "src/cli.ts",
   "type": "module",

package/src/onboarding-seed.test.ts

@@ -166,8 +166,11 @@ describe("seedOnboardingNotes — default packs (welcome + getting-started)", ()
     expect(gs!.content).toContain("## Write gotchas");
     expect(gs!.content).toContain("if_updated_at"); // optimistic concurrency
     expect(gs!.content).toContain("force: true");
-    // schema-default back-fill: enum→first value, integer→0.
-    expect(gs!.content).toContain("first listed value");
+    // schema-default back-fill is explicit-`default`-only (vault#553 Decision B).
+    expect(gs!.content).toContain("explicit `default`");
+    expect(gs!.content).toContain("exists: false");
+    // indexed⇒strict type enforcement (vault#553 Decision A).
+    expect(gs!.content).toContain("field's TYPE is always enforced");
   });
 
   test("A3 (reshaped): the welcome ring resolves to real link edges; Getting Started has no dangling Surface Starter link", async () => {

package/src/routes.ts

@@ -24,7 +24,7 @@ import {
   contentRangeRequiresContent,
   type ContentRange,
 } from "../core/src/content-range.ts";
-import { attachValidationStatus, enforceStrictWrite } from "../core/src/mcp.ts";
+import { attachValidationStatus, enforceStrictWrite, applySchemaDefaults } from "../core/src/mcp.ts";
 import type { ValidationWarning } from "../core/src/schema-defaults.ts";
 import { logStrictBypass } from "./scopes.ts";
 import * as linkOps from "../core/src/links.ts";
@@ -48,7 +48,7 @@ import {
   tagScopeForbidden,
   tagsWithinScope,
 } from "./tag-scope.ts";
-import { ParentCycleError } from "../core/src/tag-schemas.ts";
+import { ParentCycleError, InvalidFieldDefaultError } from "../core/src/tag-schemas.ts";
 import { findTokensReferencingTag } from "./token-store.ts";
 
 /**
@@ -2668,6 +2668,18 @@ export async function handleTags(
           400,
         );
       }
+      if (err instanceof InvalidFieldDefaultError) {
+        // vault#553 Decision B — a declared `default` doesn't conform to its
+        // own field's type/enum. Own-field error (no cross-tag data), so no
+        // scrub needed. Mirrors IndexedFieldError's 400 shape/posture — see
+        // store.upsertTagRecord's pre-validate comment for why REST hits
+        // this (fail-fast, single violation) while MCP's update-tag usually
+        // reports it bundled via `TagFieldConflictError` instead.
+        return json(
+          { error: err.message, error_type: "invalid_field_default", field: err.field },
+          400,
+        );
+      }
       if (err instanceof ParentCycleError) {
         // vault#552: parent_names would close a cycle. Nothing was
         // persisted. Scope-scrub the cycle path for a tag-scoped caller —
@@ -3735,56 +3747,10 @@ export async function handleStorage(
   return json({ error: "Not found", error_type: "not_found" }, 404);
 }
 
-// ---------------------------------------------------------------------------
-// Tag schema defaults — same logic as core/src/mcp.ts applySchemaDefaults
-// ---------------------------------------------------------------------------
-
-// Returns the IDs of notes whose metadata was actually default-filled, so
-// the caller can re-read ONLY the mutated notes (and skip the re-read when
-// nothing changed). Mirrors the core/src/mcp.ts contract.
-async function applySchemaDefaults(store: Store, db: any, noteIds: string[], tags: string[]): Promise<string[]> {
-  const schemas = tagSchemaOps.getTagSchemaMap(db);
-  if (Object.keys(schemas).length === 0) return [];
-
-  const defaults: Record<string, unknown> = {};
-  for (const tag of tags) {
-    const schema = schemas[tag];
-    if (!schema?.fields) continue;
-    for (const [field, fieldSchema] of Object.entries(schema.fields)) {
-      if (!(field in defaults)) {
-        defaults[field] = defaultForField(fieldSchema);
-      }
-    }
-  }
-  if (Object.keys(defaults).length === 0) return [];
-
-  const mutated: string[] = [];
-  for (const noteId of noteIds) {
-    const note = await store.getNote(noteId);
-    if (!note) continue;
-    const existing = (note.metadata as Record<string, unknown>) ?? {};
-    const missing: Record<string, unknown> = {};
-    for (const [field, value] of Object.entries(defaults)) {
-      if (!(field in existing)) missing[field] = value;
-    }
-    if (Object.keys(missing).length === 0) continue;
-    await store.updateNote(noteId, {
-      metadata: { ...existing, ...missing },
-      skipUpdatedAt: true,
-    });
-    mutated.push(noteId);
-  }
-  return mutated;
-}
-
-function defaultForField(field: { type: string; enum?: string[] }): unknown {
-  if (field.enum && field.enum.length > 0) return field.enum[0];
-  switch (field.type) {
-    case "boolean": return false;
-    case "integer": return 0;
-    default: return "";
-  }
-}
+// applySchemaDefaults lives in core/src/mcp.ts (vault#553) — REST used to
+// carry a byte-identical duplicate; importing it means REST and MCP can
+// never drift on this behavior again, and the cloud runtime (which imports
+// core directly) inherits it without any handler-side code.
 
 function removeWikilinkBrackets(content: string, targetPath: string): string {
   const escaped = targetPath.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");