@openparachute/vault 0.7.3-rc.2 → 0.7.3-rc.3

package/core/src/conformance.ts

@@ -78,7 +78,8 @@ function toStrictSchemaField(spec: TagFieldSchema): SchemaField {
     spec.type === "integer" ||
     spec.type === "boolean" ||
     spec.type === "array" ||
-    spec.type === "object"
+    spec.type === "object" ||
+    spec.type === "date"
   ) {
     out.type = spec.type;
   }

package/core/src/contract-typed-index.test.ts

@@ -220,14 +220,15 @@ describe("contract: typed indexes — Decision B: explicit-default-only enum bac
 });
 
 describe("contract: typed indexes — Decision C: honest type list (#553, flipped from todo)", () => {
-  it("the update-tag field-type description clarifies only string/integer/boolean/reference are indexable", () => {
+  it("the update-tag field-type description clarifies only string/integer/boolean/reference/date are indexable", () => {
     const updateTag = generateMcpTools(store).find((t) => t.name === "update-tag")!;
     const typeDesc = (updateTag.inputSchema as any).properties.fields.additionalProperties.properties.type.description as string;
     // Honest about the full storage/advisory vocabulary AND the indexable subset.
     expect(typeDesc).toContain("number");
     // vault#typed-reference-field: `reference` joined the indexable subset
-    // alongside string/integer/boolean.
-    expect(typeDesc).toContain("Only string/integer/boolean/reference are INDEXABLE");
+    // alongside string/integer/boolean. vault#date-field-type: `date` joined
+    // the same subset — it stores TEXT (ISO-8601), same as string/reference.
+    expect(typeDesc).toContain("Only string/integer/boolean/reference/date are INDEXABLE");
   });
 
   it("declaring indexed:true with an unindexable type (number) is rejected", async () => {

package/core/src/core.test.ts

@@ -1478,6 +1478,42 @@ describe("queryNotes", async () => {
       expect(results.map((n) => n.content)).toEqual(["recent email"]);
     });
 
+    // ---- `date` field type (vault#date-field-type) ----
+    //
+    // Same date_filter machinery as `email_date` above, but declared via a
+    // real tag schema (`type: "date", indexed: true`) rather than raw
+    // `declareField`, and mixing both accepted ISO forms (bare date + full
+    // RFC3339 timestamp) in one vault.
+    it("date_filter works on a schema-declared, indexed `date` field, accepting both ISO forms", async () => {
+      const tools = generateMcpTools(store);
+      // Indexed-field reconciliation (declareField → generated column + index)
+      // runs through the `update-tag` tool / `store.upsertTagRecord` — the
+      // legacy `store.upsertTagSchema` facade writes description+fields only
+      // and does NOT create the backing column. See store.ts's upsertTagRecord.
+      const updateTag = tools.find((t) => t.name === "update-tag")!;
+      await updateTag.execute({
+        tag: "meeting",
+        fields: { meeting_date: { type: "date", indexed: true } },
+      });
+      await store.createNote("too early", { tags: ["meeting"], metadata: { meeting_date: "2025-12-01" } });
+      await store.createNote("in window (date-only)", { tags: ["meeting"], metadata: { meeting_date: "2026-04-15" } });
+      await store.createNote("in window (full timestamp)", {
+        tags: ["meeting"],
+        metadata: { meeting_date: "2026-04-25T09:00:00.000Z" },
+      });
+      await store.createNote("too late", { tags: ["meeting"], metadata: { meeting_date: "2026-06-01" } });
+
+      const query = tools.find((t) => t.name === "query-notes")!;
+      const results = await query.execute({
+        date_filter: { field: "meeting_date", from: "2026-04-01", to: "2026-05-01" },
+        include_content: true,
+      }) as any[];
+      expect(results.map((n) => n.content).sort()).toEqual([
+        "in window (date-only)",
+        "in window (full timestamp)",
+      ]);
+    });
+
     // ---- updated_at filter (vault#285 friction point 1.5) ----
     //
     // Incremental-rebuild flows ask "what changed since X." Like `created_at`,
@@ -2230,6 +2266,50 @@ describe("queryNotes", async () => {
         store.queryNotes({ metadata: { priority: { in: 5 } as any } }),
       ).rejects.toThrow(/expects an array/);
     });
+
+    // ---- `date` field type: gt/gte/lt/lte + order_by (vault#date-field-type) ----
+    //
+    // Indexed `date` fields store TEXT (ISO-8601 strings compare correctly
+    // lexicographically), so this exercises the SAME generic string-indexed-
+    // field machinery `email_date`/`status` above already use — no
+    // date-specific SQL was added. Uses a real tag schema (`type: "date",
+    // indexed: true`), not raw `declareField`, to prove the wiring end to end.
+    it("gt/gte/lt/lte compose into range queries on an indexed `date` field", async () => {
+      // Indexed-field reconciliation (declareField → generated column +
+      // index) runs through the `update-tag` tool / `store.upsertTagRecord`
+      // — `store.upsertTagSchema` is the legacy description+fields-only
+      // facade and does NOT create the backing column.
+      const tools = generateMcpTools(store);
+      const updateTag = tools.find((t) => t.name === "update-tag")!;
+      await updateTag.execute({
+        tag: "meeting",
+        fields: { meeting_date: { type: "date", indexed: true } },
+      });
+      await store.createNote("jan", { tags: ["meeting"], metadata: { meeting_date: "2026-01-15" } });
+      await store.createNote("apr", { tags: ["meeting"], metadata: { meeting_date: "2026-04-15" } });
+      await store.createNote("jul", { tags: ["meeting"], metadata: { meeting_date: "2026-07-09T14:30:00.000Z" } });
+      await store.createNote("oct", { tags: ["meeting"], metadata: { meeting_date: "2026-10-15" } });
+
+      const range = await store.queryNotes({
+        metadata: { meeting_date: { gte: "2026-04-01", lt: "2026-10-01" } },
+      });
+      expect(range.map((n) => n.content).sort()).toEqual(["apr", "jul"]);
+    });
+
+    it("order_by sorts by an indexed `date` field", async () => {
+      const tools = generateMcpTools(store);
+      const updateTag = tools.find((t) => t.name === "update-tag")!;
+      await updateTag.execute({
+        tag: "meeting",
+        fields: { meeting_date: { type: "date", indexed: true } },
+      });
+      await store.createNote("later", { tags: ["meeting"], metadata: { meeting_date: "2026-07-09" } });
+      await store.createNote("earlier", { tags: ["meeting"], metadata: { meeting_date: "2026-01-15" } });
+      await store.createNote("middle", { tags: ["meeting"], metadata: { meeting_date: "2026-04-01" } });
+
+      const asc = await store.queryNotes({ orderBy: "meeting_date" });
+      expect(asc.map((n) => n.content)).toEqual(["earlier", "middle", "later"]);
+    });
   });
 });
 
@@ -4556,11 +4636,54 @@ describe("MCP tools", async () => {
         e: { type: "array" },
         f: { type: "object" },
         g: { type: "reference" },
+        h: { type: "date" },
       },
     }) as any;
     expect(result.fields.a.type).toBe("string");
     expect(result.fields.f.type).toBe("object");
     expect(result.fields.g.type).toBe("reference");
+    expect(result.fields.h.type).toBe("date");
+  });
+
+  // vault#date-field-type: `date` stores/validates like `string` — an
+  // ISO-8601 date or full RFC3339 timestamp — reusing cursor.ts's
+  // `timestampToMs` (the same parser `date_filter`'s `updated_at` bound
+  // uses) rather than a second, independently-drifting date parser.
+  it("update-tag accepts a `date` field's default in both ISO forms", async () => {
+    const tools = generateMcpTools(store);
+    const updateTag = tools.find((t) => t.name === "update-tag")!;
+    const dateOnly = await updateTag.execute({
+      tag: "meeting",
+      fields: { meeting_date: { type: "date", default: "2026-07-09" } },
+    }) as any;
+    expect(dateOnly.fields.meeting_date.default).toBe("2026-07-09");
+
+    const fullTimestamp = await updateTag.execute({
+      tag: "meeting",
+      fields: { meeting_date: { type: "date", default: "2026-07-09T14:30:00.000Z" } },
+    }) as any;
+    expect(fullTimestamp.fields.meeting_date.default).toBe("2026-07-09T14:30:00.000Z");
+  });
+
+  it("update-tag rejects a non-ISO default on a `date` field (invalid_default)", async () => {
+    const tools = generateMcpTools(store);
+    const updateTag = tools.find((t) => t.name === "update-tag")!;
+    let caught: any;
+    try {
+      await updateTag.execute({
+        tag: "meeting",
+        fields: { meeting_date: { type: "date", default: "not-a-date" } },
+      });
+    } catch (e) {
+      caught = e;
+    }
+    expect(caught).toBeDefined();
+    expect(caught.error_type).toBe("tag_field_conflict");
+    expect(caught.violations[0].field).toBe("meeting_date");
+    expect(caught.violations[0].reason).toBe("invalid_default");
+    // Nothing persisted.
+    const record = await store.getTagRecord("meeting");
+    expect(record?.fields ?? null).toBeFalsy();
   });
 
   // ---- Typed reference field: indexed value + auto-link (vault#typed-reference-field) ----
@@ -6050,6 +6173,113 @@ describe("schema validation (tags.fields)", async () => {
     expect(result.validation_status.warnings[0].reason).toBe("enum_mismatch");
   });
 
+  // ---- `date` field type (vault#date-field-type) ----
+  //
+  // Motivation: today a date-ish field (e.g. a `meeting` tag's
+  // `meeting_date`) can only be declared `type: "string"`, with "ISO date"
+  // explained in prose — nothing can programmatically discover
+  // date-candidate fields for a calendar view. `date` validates like
+  // `string` but requires an ISO-8601 date or full RFC3339 timestamp,
+  // parsed by the SAME `timestampToMs` (cursor.ts) `date_filter`'s
+  // `updated_at` bound uses.
+
+  it("no warning when a `date` field's value is a bare ISO date (YYYY-MM-DD)", async () => {
+    await store.upsertTagSchema("meeting", {
+      fields: { meeting_date: { type: "date" } },
+    });
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    const result = await create.execute({
+      content: "standup",
+      tags: ["meeting"],
+      metadata: { meeting_date: "2026-07-09" },
+    }) as any;
+    expect(result.validation_status.warnings).toEqual([]);
+  });
+
+  it("no warning when a `date` field's value is a full RFC3339 timestamp", async () => {
+    await store.upsertTagSchema("meeting", {
+      fields: { meeting_date: { type: "date" } },
+    });
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    const result = await create.execute({
+      content: "standup",
+      tags: ["meeting"],
+      metadata: { meeting_date: "2026-07-09T14:30:00.000Z" },
+    }) as any;
+    expect(result.validation_status.warnings).toEqual([]);
+  });
+
+  it("type_mismatch warning when a `date` field's value isn't a parseable ISO string", async () => {
+    await store.upsertTagSchema("meeting", {
+      fields: { meeting_date: { type: "date" } },
+    });
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    const result = await create.execute({
+      content: "standup",
+      tags: ["meeting"],
+      metadata: { meeting_date: "not-a-date" },
+    }) as any;
+    expect(result.validation_status.warnings).toHaveLength(1);
+    expect(result.validation_status.warnings[0].reason).toBe("type_mismatch");
+    expect(result.validation_status.warnings[0].field).toBe("meeting_date");
+  });
+
+  it("a `date` field's type_mismatch is a HARD REJECTION under strict:true, same as any other type", async () => {
+    await store.upsertTagSchema("meeting", {
+      fields: { meeting_date: { type: "date", strict: true } },
+    });
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    await expect(create.execute({
+      content: "standup",
+      tags: ["meeting"],
+      metadata: { meeting_date: "not-a-date" },
+    })).rejects.toThrow();
+  });
+
+  it("an indexed `date` field's type_mismatch is ALWAYS a hard rejection, independent of strict (vault#553 Decision A)", async () => {
+    await store.upsertTagSchema("meeting", {
+      fields: { meeting_date: { type: "date", indexed: true } },
+    });
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    await expect(create.execute({
+      content: "standup",
+      tags: ["meeting"],
+      metadata: { meeting_date: "not-a-date" },
+    })).rejects.toThrow();
+  });
+
+  // Sharp edge (docs/HTTP_API.md's "type: date" callout): a schema edit
+  // that tightens an existing field from `string` to `date` does NOT
+  // retroactively revalidate notes already carrying a non-ISO value —
+  // only the field's NEXT write is checked. No migration, no data change.
+  it("tightening an existing field from string to date does not retroactively touch existing notes", async () => {
+    await store.upsertTagSchema("meeting", {
+      fields: { meeting_date: { type: "string" } },
+    });
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    const query = tools.find((t) => t.name === "query-notes")!;
+    const note = await create.execute({
+      content: "old-style note",
+      tags: ["meeting"],
+      metadata: { meeting_date: "sometime next week" }, // not ISO — fine under type:"string"
+    }) as any;
+    expect(note.validation_status.warnings).toEqual([]);
+
+    // Tighten the schema. This must not touch the existing note.
+    await store.upsertTagSchema("meeting", {
+      fields: { meeting_date: { type: "date" } },
+    });
+
+    const fresh = await query.execute({ id: note.id }) as any;
+    expect(fresh.metadata.meeting_date).toBe("sometime next week");
+  });
+
   // vault#555 fix 3 — an enum-membership violation on an INDEXED
   // (non-strict) field is stored, findable via `eq` (indexed⇒strict is
   // TYPE-only, not enum-domain — a ratified policy, not a bug), but the
@@ -6346,6 +6576,212 @@ describe("schema validation (tags.fields)", async () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// `date` field type — offset normalization on write (vault#date-field-type
+// review fix). A raw TEXT compare only sorts ISO-8601 timestamps correctly
+// when every stored value shares the SAME offset representation.
+// `timestampToMs` correctly VALIDATES an explicit ±HH:MM offset, but the
+// value used to persist VERBATIM — a mixed-offset vault silently
+// mis-ordered/mis-filtered. `normalizeDateFields` (schema-defaults.ts),
+// wired into every store write path, rewrites a full timestamp to canonical
+// UTC (`Z`-suffixed) before the row is written.
+// ---------------------------------------------------------------------------
+
+describe("date field type — offset normalization (vault#date-field-type review fix)", async () => {
+  async function declareIndexedMeetingDate() {
+    const tools = generateMcpTools(store);
+    const updateTag = tools.find((t) => t.name === "update-tag")!;
+    await updateTag.execute({
+      tag: "meeting",
+      fields: { meeting_date: { type: "date", indexed: true } },
+    });
+    return tools;
+  }
+
+  // The reviewer's exact repro: "2026-07-16T10:00:00+02:00" (= 08:00Z) vs
+  // "2026-07-16T09:00:00Z" (= 09:00Z). Persisted verbatim, a raw string
+  // compare gets these BACKWARDS (comparing "10" vs "09" after the shared
+  // "2026-07-16T" prefix says the +02:00 value sorts LATER, when its actual
+  // instant — 08:00Z — is EARLIER). Post-normalization both values are
+  // Z-form UTC, so the string compare IS the instant compare.
+  it("order_by ASC returns mixed-offset values in true chronological order", async () => {
+    const tools = await declareIndexedMeetingDate();
+    const create = tools.find((t) => t.name === "create-note")!;
+    await create.execute({
+      content: "earlier (offset form)",
+      tags: ["meeting"],
+      metadata: { meeting_date: "2026-07-16T10:00:00+02:00" }, // = 08:00Z
+    });
+    await create.execute({
+      content: "later (Z form)",
+      tags: ["meeting"],
+      metadata: { meeting_date: "2026-07-16T09:00:00Z" }, // = 09:00Z
+    });
+
+    const asc = await store.queryNotes({ orderBy: "meeting_date" });
+    expect(asc.map((n) => n.content)).toEqual(["earlier (offset form)", "later (Z form)"]);
+  });
+
+  it("a gt bound correctly excludes an earlier instant expressed with an offset", async () => {
+    const tools = await declareIndexedMeetingDate();
+    const create = tools.find((t) => t.name === "create-note")!;
+    await create.execute({
+      content: "before threshold (offset form, = 08:00Z)",
+      tags: ["meeting"],
+      metadata: { meeting_date: "2026-07-16T10:00:00+02:00" },
+    });
+    await create.execute({
+      content: "after threshold (Z form, = 09:00Z)",
+      tags: ["meeting"],
+      metadata: { meeting_date: "2026-07-16T09:00:00Z" },
+    });
+
+    // Threshold sits BETWEEN the two instants (08:30Z). Pre-fix, the
+    // unnormalized "+02:00" value's raw string ("...10:00:00+02:00")
+    // compared GREATER than the threshold string despite its instant being
+    // earlier — a false match. Post-fix it correctly falls below.
+    const results = await store.queryNotes({
+      metadata: { meeting_date: { gt: "2026-07-16T08:30:00Z" } },
+    });
+    expect(results.map((n) => n.content)).toEqual(["after threshold (Z form, = 09:00Z)"]);
+  });
+
+  it("create-note normalizes an offset timestamp to canonical Z-form; the stored/returned value is not the verbatim input", async () => {
+    const tools = await declareIndexedMeetingDate();
+    const create = tools.find((t) => t.name === "create-note")!;
+    const query = tools.find((t) => t.name === "query-notes")!;
+    const created = await create.execute({
+      content: "standup",
+      tags: ["meeting"],
+      metadata: { meeting_date: "2026-07-16T10:00:00+02:00" },
+    }) as any;
+
+    // The create response itself already reflects the normalized value...
+    expect(created.metadata.meeting_date).toBe("2026-07-16T08:00:00.000Z");
+    // ...and so does a fresh read-back (round-trips through the DB, not an echo).
+    const fresh = await query.execute({ id: created.id }) as any;
+    expect(fresh.metadata.meeting_date).toBe("2026-07-16T08:00:00.000Z");
+  });
+
+  it("update-note (merge-patch) normalizes an offset timestamp the same way create-note does", async () => {
+    const tools = await declareIndexedMeetingDate();
+    const create = tools.find((t) => t.name === "create-note")!;
+    const update = tools.find((t) => t.name === "update-note")!;
+    const query = tools.find((t) => t.name === "query-notes")!;
+    const created = await create.execute({
+      content: "standup",
+      tags: ["meeting"],
+    }) as any;
+
+    await update.execute({
+      id: created.id,
+      metadata: { meeting_date: "2026-07-16T10:00:00+02:00" },
+      force: true,
+    });
+
+    const fresh = await query.execute({ id: created.id }) as any;
+    expect(fresh.metadata.meeting_date).toBe("2026-07-16T08:00:00.000Z");
+  });
+
+  // ---- round 2: tag-add + date-metadata in the SAME call (vault#date-
+  // field-type review round 2) ----
+  //
+  // `store.tagNote` (the actual tag mutation) runs AFTER the core UPDATE in
+  // both mcp.ts call sites that combine tags + metadata in one item — the
+  // reviewer live-verified that without passing the PROJECTED tag set into
+  // `store.updateNote`, normalization resolved the schema against the
+  // note's STALE pre-write tags and missed a field newly declared by the
+  // tag being added in this same call.
+
+  it("update-note: tags.add + an offset date value in the SAME call still normalizes (bare, untagged note)", async () => {
+    const tools = await declareIndexedMeetingDate();
+    const create = tools.find((t) => t.name === "create-note")!;
+    const update = tools.find((t) => t.name === "update-note")!;
+    const query = tools.find((t) => t.name === "query-notes")!;
+    // Bare, untagged note — "meeting" (and its meeting_date:date field) is
+    // NOT yet on this note; it's added in the SAME update-note call below.
+    const created = await create.execute({ content: "standup" }) as any;
+
+    const result = await update.execute({
+      id: created.id,
+      tags: { add: ["meeting"] },
+      metadata: { meeting_date: "2026-07-16T10:00:00+02:00" },
+      force: true,
+    }) as any;
+
+    expect(result.metadata.meeting_date).toBe("2026-07-16T08:00:00.000Z");
+    const fresh = await query.execute({ id: created.id }) as any;
+    expect(fresh.metadata.meeting_date).toBe("2026-07-16T08:00:00.000Z");
+    expect(fresh.tags).toContain("meeting");
+  });
+
+  it("create-note if_exists:update: tags + an offset date value in the SAME call still normalizes (bare, untagged note)", async () => {
+    const tools = await declareIndexedMeetingDate();
+    const create = tools.find((t) => t.name === "create-note")!;
+    const query = tools.find((t) => t.name === "query-notes")!;
+    const created = await create.execute({ content: "standup", path: "Inbox/round2-upsert" }) as any;
+
+    const result = await create.execute({
+      path: "Inbox/round2-upsert",
+      tags: ["meeting"],
+      metadata: { meeting_date: "2026-07-16T10:00:00+02:00" },
+      if_exists: "update",
+    }) as any;
+
+    expect(result.metadata.meeting_date).toBe("2026-07-16T08:00:00.000Z");
+    const fresh = await query.execute({ id: created.id }) as any;
+    expect(fresh.metadata.meeting_date).toBe("2026-07-16T08:00:00.000Z");
+    expect(fresh.tags).toContain("meeting");
+  });
+
+  // ---- round 2: copy-on-write, never mutate the caller's object ----
+
+  it("store.createNote does NOT mutate the caller's metadata object", async () => {
+    await declareIndexedMeetingDate();
+    const callerMetadata = { meeting_date: "2026-07-16T10:00:00+02:00" };
+    const callerMetadataSnapshot = { ...callerMetadata };
+    await store.createNote("standup", { tags: ["meeting"], metadata: callerMetadata });
+    // The caller's own object must be byte-identical to before the call —
+    // core is a published library; a direct embedder's reference must
+    // never change out from under them.
+    expect(callerMetadata).toEqual(callerMetadataSnapshot);
+  });
+
+  it("store.updateNote does NOT mutate the caller's metadata object", async () => {
+    await declareIndexedMeetingDate();
+    const note = await store.createNote("standup", { tags: ["meeting"] });
+    const callerMetadata = { meeting_date: "2026-07-16T10:00:00+02:00" };
+    const callerMetadataSnapshot = { ...callerMetadata };
+    await store.updateNote(note.id, { metadata: callerMetadata });
+    expect(callerMetadata).toEqual(callerMetadataSnapshot);
+  });
+
+  it("a bare YYYY-MM-DD value passes through untouched (no offset to normalize)", async () => {
+    const tools = await declareIndexedMeetingDate();
+    const create = tools.find((t) => t.name === "create-note")!;
+    const query = tools.find((t) => t.name === "query-notes")!;
+    const created = await create.execute({
+      content: "standup",
+      tags: ["meeting"],
+      metadata: { meeting_date: "2026-07-16" },
+    }) as any;
+    expect(created.metadata.meeting_date).toBe("2026-07-16");
+    const fresh = await query.execute({ id: created.id }) as any;
+    expect(fresh.metadata.meeting_date).toBe("2026-07-16");
+  });
+
+  it("a value already in canonical Z-form passes through unchanged (no spurious rewrite)", async () => {
+    const tools = await declareIndexedMeetingDate();
+    const create = tools.find((t) => t.name === "create-note")!;
+    const created = await create.execute({
+      content: "standup",
+      tags: ["meeting"],
+      metadata: { meeting_date: "2026-07-16T09:00:00.000Z" },
+    }) as any;
+    expect(created.metadata.meeting_date).toBe("2026-07-16T09:00:00.000Z");
+  });
+});
+
 // ---------------------------------------------------------------------------
 // update-note `if_missing: "create"` — idempotent upsert (vault#309)
 // ---------------------------------------------------------------------------
@@ -8128,6 +8564,25 @@ describe("vault projection (vault#271)", async () => {
     expect(byName.priority.tags).toEqual(["project"]);
   });
 
+  // vault#date-field-type: `type: "date"` carries through the indexed-field
+  // catalog like any other type — nothing in the projection filters unknown
+  // or newer types out.
+  it("catalogs an indexed `date` field with its declared type", async () => {
+    const { buildVaultProjection } = await import("./vault-projection.ts");
+    const tools = generateMcpTools(store);
+    const updateTag = tools.find((t) => t.name === "update-tag")!;
+    await updateTag.execute({
+      tag: "meeting",
+      fields: { meeting_date: { type: "date", indexed: true } },
+    });
+
+    const projection = buildVaultProjection(db);
+    const byName = Object.fromEntries(projection.indexed_fields.map((f) => [f.name, f]));
+    expect(byName.meeting_date).toBeTruthy();
+    expect(byName.meeting_date.type).toBe("date");
+    expect(byName.meeting_date.tags).toEqual(["meeting"]);
+  });
+
   it("includes the static query-hint catalog", async () => {
     const { buildVaultProjection, QUERY_HINTS } = await import("./vault-projection.ts");
     const projection = buildVaultProjection(db);

package/core/src/indexed-fields.test.ts

@@ -67,13 +67,16 @@ describe("indexed-fields: module", () => {
     expect(() => validateFieldName("'; DROP TABLE notes; --")).toThrow(IndexedFieldError);
   });
 
-  it("TYPE_MAP covers string/integer/boolean/reference", () => {
+  it("TYPE_MAP covers string/integer/boolean/reference/date", () => {
     expect(TYPE_MAP.string).toBe("TEXT");
     expect(TYPE_MAP.integer).toBe("INTEGER");
     expect(TYPE_MAP.boolean).toBe("INTEGER");
     // vault#typed-reference-field: `reference` stores like `string` — the
     // metadata VALUE (an id/path/title) is what's indexed here.
     expect(TYPE_MAP.reference).toBe("TEXT");
+    // vault#date-field-type: `date` also stores like `string` — an ISO-8601
+    // string, which sorts correctly under a plain TEXT comparison.
+    expect(TYPE_MAP.date).toBe("TEXT");
   });
 
   it("declareField creates column + index on first declaration", () => {
@@ -212,12 +215,15 @@ describe("update-tag: indexed flag", () => {
   });
 
   it("unsupported field type for indexing throws", async () => {
+    // vault#date-field-type: `date` JOINED the indexable subset (stores TEXT,
+    // same as string/reference) — `number` (a float) is the current example
+    // of a recognized-but-unindexable type; see TYPE_MAP.
     expect(() =>
       findTool("update-tag").execute({
         tag: "project",
-        fields: { weird: { type: "date", indexed: true } },
+        fields: { weird: { type: "number", indexed: true } },
       }),
-    ).toThrow(/unsupported type "date"/);
+    ).toThrow(/unsupported type "number"/);
   });
 
   it("invalid field name for indexing throws", async () => {

package/core/src/indexed-fields.ts

@@ -27,13 +27,21 @@ export type SqliteType = "TEXT" | "INTEGER";
 // `string` — because the metadata VALUE (an id/path/title) is what's
 // indexed here; the resolved graph link is a separate concern maintained by
 // `core/src/store.ts`'s write path. See tag-schemas.ts's `VALID_FIELD_TYPES`.
-export type FieldType = "string" | "integer" | "boolean" | "reference";
+// `date` is also stored as TEXT: an indexed `date` field holds an ISO-8601
+// string (validated by `tag-schemas.ts`'s `defaultMatchesType` /
+// `schema-defaults.ts`'s `valueMatchesType`), and ISO-8601 strings are
+// lexicographically comparable — the same reason TEXT-stored `updated_at`
+// range queries already work — so `gt`/`gte`/`lt`/`lte`, `date_filter`, and
+// `order_by` all fall out of the generic TEXT-column machinery with no
+// type-specific SQL.
+export type FieldType = "string" | "integer" | "boolean" | "reference" | "date";
 
 export const TYPE_MAP: Record<FieldType, SqliteType> = {
   string: "TEXT",
   integer: "INTEGER",
   boolean: "INTEGER",
   reference: "TEXT",
+  date: "TEXT",
 };
 
 export interface IndexedField {

package/core/src/mcp.ts

@@ -1355,6 +1355,12 @@ A note's response carries \`existed\` (true/false) whenever ITS \`if_exists\` wa
               ...updates,
               actor: writeActor,
               via: writeVia,
+              // `tagsForSchemaResolution` (vault#date-field-type review round
+              // 2) — same bug/fix as the update-note handler: `store.tagNote`
+              // below runs AFTER this UPDATE, so without the PROJECTED tag
+              // set here, `date`-field normalization inside store.updateNote
+              // would miss a field newly declared by an incoming tag.
+              tagsForSchemaResolution: [...projectedTags],
             });
           }
 
@@ -2070,10 +2076,18 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
             // --- Strict-schema gate (vault#299 Part A) ---
             // Validate the PROSPECTIVE shape (final tags + merged metadata,
             // including a state_transition's `to`) before the write so a
-            // rejection leaves the note untouched.
+            // rejection leaves the note untouched. `projectedTags` is hoisted
+            // out of this block (not just used here) — the `store.updateNote`
+            // call below also needs it, as `tagsForSchemaResolution`, so that
+            // `date`-field normalization sees a tag ADDED in this SAME call
+            // (vault#date-field-type review round 2 — the actual `store.tagNote`
+            // mutation happens AFTER the core UPDATE, so without this the
+            // schema resolution inside `store.updateNote` would still be
+            // looking at the note's stale pre-write tag set).
+            let projectedTags: Set<string>;
             {
               const removeSet = new Set<string>((item.tags as any)?.remove ?? []);
-              const projectedTags = new Set<string>((note.tags ?? []).filter((t) => !removeSet.has(t)));
+              projectedTags = new Set<string>((note.tags ?? []).filter((t) => !removeSet.has(t)));
               for (const t of ((item.tags as any)?.add as string[] | undefined) ?? []) projectedTags.add(t);
               const baseMeta = updates.metadata ?? ((note.metadata as Record<string, unknown>) ?? {});
               const projectedMeta = stItem !== undefined
@@ -2117,6 +2131,12 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
               // updated_at on a no-op).
               updates.actor = writeActor;
               updates.via = writeVia;
+              // `tagsForSchemaResolution` (vault#date-field-type review round
+              // 2) — the PROJECTED final tag set, so `date`-field
+              // normalization inside store.updateNote sees a tag ADDED in
+              // this same call, not just the note's pre-write tags. See the
+              // comment on `projectedTags`'s declaration above.
+              updates.tagsForSchemaResolution = [...projectedTags];
               // store.updateNote routes through noteOps.updateNote, which runs
               // the UPDATE (with optional `AND updated_at IS ?`) atomically and
               // throws ConflictError on mismatch. No mutations have happened
@@ -2380,11 +2400,11 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
             additionalProperties: {
               type: "object",
               properties: {
-                type: { type: "string", description: "Field type: string, boolean, integer, number, array, object, reference — all seven are accepted for storage + advisory validation; any OTHER value is rejected outright (error_type invalid_field_type, vault#555 — bundled with every other violation in the same call, see the `update-tag` tool description). Only string/integer/boolean/reference are INDEXABLE (see `indexed` below); declaring `indexed: true` with number/array/object is rejected (unsupported_indexed_type / invalid_indexed_field). `reference` is a DUAL-WRITE type (typed-reference-field): the value is stored + validated exactly like `string` (pass a note id, path, or title), AND create-note/update-note additionally resolve that value to a note and maintain a graph `links` edge from this note to it, with `relationship` set to the field name — kept in sync on every write that changes the field (a new value re-points the link; clearing the field drops it). A target that doesn't resolve yet is queued and backfills automatically, same as a structured `links` entry — see `docs/design/typed-reference-field.md`." },
+                type: { type: "string", description: "Field type: string, boolean, integer, number, array, object, reference, date — all eight are accepted for storage + advisory validation; any OTHER value is rejected outright (error_type invalid_field_type, vault#555 — bundled with every other violation in the same call, see the `update-tag` tool description). Only string/integer/boolean/reference/date are INDEXABLE (see `indexed` below); declaring `indexed: true` with number/array/object is rejected (unsupported_indexed_type / invalid_indexed_field). `reference` is a DUAL-WRITE type (typed-reference-field): the value is stored + validated exactly like `string` (pass a note id, path, or title), AND create-note/update-note additionally resolve that value to a note and maintain a graph `links` edge from this note to it, with `relationship` set to the field name — kept in sync on every write that changes the field (a new value re-points the link; clearing the field drops it). A target that doesn't resolve yet is queued and backfills automatically, same as a structured `links` entry — see `docs/design/typed-reference-field.md`. `date` stores/validates exactly like `string`, but the value must be an ISO-8601 date (`2026-07-09`) or full timestamp (`2026-07-09T00:00:00.000Z`) — an unparseable value is a type_mismatch (advisory) or a rejected write (`strict: true` / `indexed: true`), same treatment as any other type mismatch. A full timestamp carrying an explicit `±HH:MM` offset is normalized to canonical UTC (`Z`-suffixed) on write — the offset is accepted, but not persisted verbatim — so indexed `date` fields sort/filter correctly under the TEXT comparison `gt`/`gte`/`lt`/`lte`/`date_filter`/`order_by` all use; a bare date (no time component) is left as-is." },
                 description: { type: "string" },
                 enum: { type: "array", items: { type: "string" }, description: "Allowed values. Does NOT auto-backfill — a note that omits this field stays without it unless `default` is also set (vault#553; the pre-0.7.0 behavior of silently defaulting to the first enum value is retired). Set `default` explicitly if you want backfill." },
                 default: { description: "Explicit backfill value (vault#553) applied when a note gains this tag without setting the field. Must conform to this field's own `type` (and `enum`, if declared) — a non-conforming default is rejected (invalid_default / invalid_field_default) rather than silently stored. Omit entirely to leave the field ABSENT (not backfilled) on notes that don't set it — this is what makes `exists:false` a trustworthy \"never set\" query." },
-                indexed: { type: "boolean", description: "When true, a generated column + index are maintained on notes.metadata.<field>, making it queryable via metadata operator objects and order_by. Global: all tags declaring the field must agree on both type and indexed. Only string/integer/boolean/reference are indexable. Indexed ⇒ a type-mismatched write is HARD-REJECTED (schema_validation), not just warned — vault#553." },
+                indexed: { type: "boolean", description: "When true, a generated column + index are maintained on notes.metadata.<field>, making it queryable via metadata operator objects and order_by. Global: all tags declaring the field must agree on both type and indexed. Only string/integer/boolean/reference/date are indexable. Indexed ⇒ a type-mismatched write is HARD-REJECTED (schema_validation), not just warned — vault#553." },
                 strict: { type: "boolean", description: "vault#299. Default false (advisory). When true, ALL of this field's declared constraints (type + enum + required + cardinality) are ENFORCED — a violating write is rejected with a schema_validation error, not just warned. All-or-nothing per field; free-form fields on a strict tag simply leave strict off. Note: `indexed: true` fields enforce their TYPE constraint regardless of this flag (vault#553)." },
                 required: { type: "boolean", description: "vault#299. The field must be present + non-null on a note with this tag. Advisory unless `strict: true`." },
                 cardinality: { type: "string", enum: ["one", "many"], description: "vault#299. 'one' (scalar, default) or 'many' (array). Advisory unless `strict: true`." },

package/core/src/schema-defaults.ts

@@ -41,6 +41,7 @@
  */
 
 import { Database } from "bun:sqlite";
+import { timestampToMs } from "./cursor.js";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -57,7 +58,7 @@ export interface SchemaField {
    * `type_mismatch` warning that previously fired on every integer-shaped
    * field because the validator had no `"integer"` case. See vault#310.
    */
-  type?: "string" | "number" | "integer" | "boolean" | "array" | "object" | "reference";
+  type?: "string" | "number" | "integer" | "boolean" | "array" | "object" | "reference" | "date";
   enum?: string[];
   description?: string;
   /**
@@ -320,6 +321,82 @@ export function resolveNoteSchemas(
   return { effectiveTags, mergedFields, conflicts };
 }
 
+/**
+ * Normalize `date`-typed field VALUES in `metadata` to canonical UTC ISO
+ * form (`Z`-suffixed) BEFORE persisting (vault#date-field-type — mixed-
+ * offset corruption, caught in review).
+ *
+ * The bug: every consumer of an indexed `date` field — `buildOperatorClause`
+ * (query-operators.ts), `date_filter` and `order_by` (notes.ts) — compares
+ * the generated `meta_<field>` column as raw TEXT. ISO-8601 strings sort
+ * correctly under a TEXT compare ONLY when every value shares the same
+ * offset representation. `timestampToMs` (cursor.ts) — the validator both
+ * `defaultMatchesType` and `valueMatchesType` reuse — correctly ACCEPTS an
+ * explicit `±HH:MM` offset (validation was never the gap), but a value like
+ * `"2026-07-16T10:00:00+02:00"` (= `08:00Z`) persisted VERBATIM sorts AFTER
+ * `"2026-07-16T09:00:00Z"` (= `09:00Z`) under a raw string compare, even
+ * though the actual instant is earlier — a mixed-offset vault silently gets
+ * wrong range-query/order_by/date_filter results. This is the exact bug
+ * class `updated_at` got a dedicated ms-mirror column for (vault#585/#586,
+ * see `notes.ts`'s `dateFilter` block) that never extended to user-declared
+ * `date` fields.
+ *
+ * The fix is normalize-on-write, not reject-on-write (matching the
+ * "paths are normalized on write" precedent — instant preserved,
+ * representation canonicalized) — rejecting offsets would defeat the
+ * type's own motivation (calendar integrations and other emitters commonly
+ * produce offset timestamps, not always `Z`). Only a FULL timestamp (has a
+ * time component) is rewritten, to `new Date(ms).toISOString()` — always
+ * UTC, millisecond precision, `Z`-suffixed. A bare `YYYY-MM-DD` value is
+ * left untouched: it has no offset to normalize, is already canonical, and
+ * prefix-sorts correctly against full timestamps sharing the same calendar
+ * day. A value that fails `timestampToMs` is left untouched too — that's a
+ * `type_mismatch` for `valueMatchesType` to catch, not this function's job.
+ *
+ * COPY-ON-WRITE, never mutates the input `metadata` object (vault#date-
+ * field-type review round 2) — `core/` is a published library; a direct
+ * embedder holding a reference to the object THEY passed in must never see
+ * it change out from under them. Returns the SAME reference when nothing
+ * needs rewriting (the common case — no unnecessary allocation on the
+ * no-op path) or `metadata` is undefined; returns a freshly shallow-copied
+ * object, with only the rewritten field(s) replaced, the first time a
+ * rewrite is actually needed. Every call site must use the RETURNED value
+ * (not assume its input was mutated) — see `store.createNote`/`updateNote`/
+ * `createNotes`/`createNoteRaw`, all of which reassign their local
+ * `opts`/`updates`/`input` binding from the return rather than relying on a
+ * side effect.
+ *
+ * Called from `store.createNote`/`updateNote`/`createNotes`/`createNoteRaw`
+ * — the lowest chokepoint every write path (MCP, REST, import) funnels
+ * through — BEFORE the row is persisted, so the value that's validated by
+ * `validateNote`/`valueMatchesType` upstream (offset-tolerant, so
+ * normalization can't newly fail a write) and the value that's written +
+ * echoed back on the response are the SAME normalized string.
+ */
+export function normalizeDateFields(
+  resolved: ResolvedSchemas,
+  note: { tags?: string[]; metadata?: Record<string, unknown> },
+): Record<string, unknown> | undefined {
+  const metadata = note.metadata;
+  if (!metadata) return metadata;
+  const { mergedFields } = resolveNoteSchemas(resolved, note);
+  let copy: Record<string, unknown> | undefined;
+  for (const [fieldName, { spec }] of mergedFields) {
+    if (spec.type !== "date") continue;
+    const value = metadata[fieldName];
+    if (typeof value !== "string") continue;
+    // Bare `YYYY-MM-DD` (no time component) has no offset to normalize.
+    if (/^\d{4}-\d{2}-\d{2}$/.test(value)) continue;
+    const ms = timestampToMs(value);
+    if (ms === null) continue; // unparseable — valueMatchesType's job, not ours
+    const canonical = new Date(ms).toISOString();
+    if (canonical === value) continue;
+    if (!copy) copy = { ...metadata }; // lazy: only copy once a rewrite is due
+    copy[fieldName] = canonical;
+  }
+  return copy ?? metadata;
+}
+
 function fieldSpecsEqual(a: SchemaField, b: SchemaField): boolean {
   if (a.type !== b.type) return false;
   if (!stringArraysEqual(a.enum, b.enum)) return false;
@@ -390,6 +467,13 @@ function valueMatchesType(value: unknown, type: SchemaField["type"], cardinality
         return Array.isArray(value) && value.every((item) => typeof item === "string");
       }
       return typeof value === "string";
+    // `date` validates like `string` — an ISO-8601 date (`YYYY-MM-DD`) or
+    // full RFC3339 timestamp. Reuses `cursor.ts`'s `timestampToMs` (the SAME
+    // UTC-correct parser `date_filter`'s `updated_at` bound uses), not a
+    // second date parser — see tag-schemas.ts's `VALID_FIELD_TYPES` doc
+    // comment.
+    case "date":
+      return typeof value === "string" && timestampToMs(value) !== null;
   }
 }
 

package/core/src/store.ts

@@ -38,6 +38,7 @@ import {
   loadSchemaConfig,
   validateNote as runValidateNote,
   resolveNoteSchemas,
+  normalizeDateFields,
   type ResolvedSchemas,
   type ValidationStatus,
 } from "./schema-defaults.js";
@@ -500,6 +501,16 @@ export class BunSqliteStore implements Store {
   // ---- Notes ----
 
   async createNote(content: string, opts?: { id?: string; path?: string; tags?: string[]; metadata?: Record<string, unknown>; created_at?: string; extension?: string; actor?: string | null; via?: string | null }): Promise<Note> {
+    // Normalize `date`-typed field values to canonical UTC ISO form BEFORE
+    // the write (vault#date-field-type — mixed-offset TEXT-compare
+    // corruption). COPY-ON-WRITE (round 2) — reassign the local `opts`
+    // binding from the returned value rather than mutating the caller's
+    // object; see `normalizeDateFields`'s doc comment.
+    if (opts?.metadata) {
+      const normalized = normalizeDateFields(this.getSchemaConfig(), { tags: opts.tags, metadata: opts.metadata });
+      if (normalized !== opts.metadata) opts = { ...opts, metadata: normalized };
+    }
+
     const note = noteOps.createNote(this.db, content, opts);
 
     if (content) {
@@ -548,6 +559,20 @@ export class BunSqliteStore implements Store {
       actor?: string | null;
       via?: string | null;
       if_updated_at?: string;
+      /**
+       * `date`-field normalization override (vault#date-field-type review
+       * round 2). By default, `normalizeDateFields` below resolves the note's
+       * effective schema against its CURRENT tags in the DB — correct when
+       * this call doesn't also change tags. A caller that adds a tag IN THIS
+       * SAME logical update (via a separate `store.tagNote` issued right
+       * after this call — see mcp.ts's `update-note` handler and the batch
+       * upsert "update"/"replace" branch) must pass the PROJECTED final tag
+       * set here instead, or a newly-added tag's `type: "date"` field never
+       * gets seen (the schema resolution would still be looking at the
+       * pre-write tag set) and its offset-bearing value would persist
+       * verbatim. Ignored when `updates.metadata` is undefined.
+       */
+      tagsForSchemaResolution?: string[];
     },
   ): Promise<Note> {
     let oldPath: string | undefined;
@@ -561,7 +586,19 @@ export class BunSqliteStore implements Store {
     if (updates.path !== undefined || updates.metadata !== undefined) {
       const existing = noteOps.getNote(this.db, id);
       if (updates.path !== undefined) oldPath = existing?.path;
-      if (updates.metadata !== undefined) priorMetadataForRefs = existing?.metadata;
+      if (updates.metadata !== undefined) {
+        priorMetadataForRefs = existing?.metadata;
+        // Normalize `date`-typed field values to canonical UTC ISO form
+        // BEFORE the write (vault#date-field-type — mixed-offset TEXT-
+        // compare corruption). COPY-ON-WRITE (round 2) — reassign the local
+        // `updates` binding from the returned value rather than mutating the
+        // caller's object; see `normalizeDateFields`'s doc comment.
+        // `tagsForSchemaResolution` (when the caller is ALSO adding a tag in
+        // this same logical update) wins over the note's current DB tags.
+        const tagsForResolution = updates.tagsForSchemaResolution ?? existing?.tags;
+        const normalized = normalizeDateFields(this.getSchemaConfig(), { tags: tagsForResolution, metadata: updates.metadata });
+        if (normalized !== updates.metadata) updates = { ...updates, metadata: normalized };
+      }
     }
 
     const note = noteOps.updateNote(this.db, id, updates);
@@ -1034,7 +1071,18 @@ export class BunSqliteStore implements Store {
   // ---- Bulk Operations ----
 
   async createNotes(inputs: noteOps.BulkNoteInput[]): Promise<Note[]> {
-    const notes = noteOps.createNotes(this.db, inputs);
+    // Same pre-write `date`-field normalization as singleton createNote
+    // (vault#date-field-type) — this bulk path bypasses it otherwise.
+    // COPY-ON-WRITE (round 2) — build a new array with only the items that
+    // actually need a rewrite replaced; never mutate the caller's `inputs`
+    // or its element objects.
+    const schemaConfig = this.getSchemaConfig();
+    const normalizedInputs = inputs.map((input) => {
+      if (!input.metadata) return input;
+      const normalized = normalizeDateFields(schemaConfig, { tags: input.tags, metadata: input.metadata });
+      return normalized !== input.metadata ? { ...input, metadata: normalized } : input;
+    });
+    const notes = noteOps.createNotes(this.db, normalizedInputs);
     for (const note of notes) {
       // Bulk path needs the same config-cache invalidation as singleton
       // createNote — without it, a batch that includes `_tags/*` notes
@@ -1244,7 +1292,7 @@ export class BunSqliteStore implements Store {
         const mapped = indexedFieldOps.mapFieldType(spec.type);
         if (!mapped) {
           throw new indexedFieldOps.IndexedFieldError(
-            `field "${fieldName}" has unsupported type "${spec.type}" for indexing (supported: string, integer, boolean, reference)`,
+            `field "${fieldName}" has unsupported type "${spec.type}" for indexing (supported: string, integer, boolean, reference, date)`,
           );
         }
         // Throws IndexedFieldError on an invalid identifier (e.g. kebab-case).
@@ -1376,6 +1424,14 @@ export class BunSqliteStore implements Store {
    * place.)
    */
   async createNoteRaw(content: string, opts?: { id?: string; path?: string; tags?: string[]; metadata?: Record<string, unknown>; created_at?: string; extension?: string }): Promise<Note> {
+    // Same pre-write `date`-field normalization as createNote
+    // (vault#date-field-type) — the legacy Obsidian importer (obsidian.ts)
+    // funnels through this path and bypasses createNote's copy otherwise.
+    // COPY-ON-WRITE (round 2) — see normalizeDateFields's doc comment.
+    if (opts?.metadata) {
+      const normalized = normalizeDateFields(this.getSchemaConfig(), { tags: opts.tags, metadata: opts.metadata });
+      if (normalized !== opts.metadata) opts = { ...opts, metadata: normalized };
+    }
     return noteOps.createNote(this.db, content, opts);
   }
 

package/core/src/tag-schemas.ts

@@ -18,6 +18,7 @@
 import { Database } from "bun:sqlite";
 import { mapFieldType, validateFieldName } from "./indexed-fields.js";
 import { loadTagHierarchy, findParentCycle } from "./tag-hierarchy.js";
+import { timestampToMs } from "./cursor.js";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -192,7 +193,7 @@ export class InvalidFieldDefaultError extends Error {
 
 /**
  * Thrown by `upsertTagRecord` (core/src/store.ts's chokepoint) when a
- * field's declared `type` isn't one of the six recognized values (vault#555
+ * field's declared `type` isn't one of the recognized values (vault#555
  * — `update-tag{fields:{weird:{type:"frobnicator"}}}` used to be accepted
  * and persisted verbatim, no error, for any NON-indexed field: the only
  * existing type check, `mapFieldType`, ran solely on `indexed: true` fields
@@ -255,13 +256,13 @@ export function validateFieldDefault(field: string, spec: TagFieldSchema): TagFi
 
 /**
  * The full recognized vocabulary for `TagFieldSchema.type` — storage/
- * advisory validation accepts all seven; only `string`/`integer`/`boolean`/
- * `reference` are INDEXABLE (that narrower subset is `indexed-fields.ts`'s
- * `TYPE_MAP`, enforced separately via `mapFieldType` for `indexed: true`
- * fields). Matches `defaultMatchesType`'s switch and `schema-defaults.ts`'s
- * `SchemaField.type` union — kept in lockstep by hand across the two
- * deliberately-decoupled modules (see `validateFieldDefault`'s doc comment
- * for why they don't cross-import).
+ * advisory validation accepts all eight; only `string`/`integer`/`boolean`/
+ * `reference`/`date` are INDEXABLE (that narrower subset is
+ * `indexed-fields.ts`'s `TYPE_MAP`, enforced separately via `mapFieldType`
+ * for `indexed: true` fields). Matches `defaultMatchesType`'s switch and
+ * `schema-defaults.ts`'s `SchemaField.type` union — kept in lockstep by hand
+ * across the two deliberately-decoupled modules (see `validateFieldDefault`'s
+ * doc comment for why they don't cross-import).
  *
  * `reference` (vault#typed-reference-field) is a dual-write field type: the
  * value is stored + validated exactly like `string` (an id/path/title the
@@ -270,11 +271,18 @@ export function validateFieldDefault(field: string, spec: TagFieldSchema): TagFi
  * to a note and maintains a graph `links` edge from this note to the
  * resolved target, with `relationship` set to the field name. See
  * `docs/design/typed-reference-field.md` for the full design + known gaps.
+ *
+ * `date` stores/validates like `string` (an ISO-8601 date or timestamp) so
+ * indexed `date` fields sort correctly under a plain TEXT comparison — see
+ * `defaultMatchesType`'s `"date"` case and `schema-defaults.ts`'s
+ * `valueMatchesType`, both of which reuse `cursor.ts`'s `timestampToMs`
+ * (the SAME UTC-correct parser `date_filter`'s `updated_at` bound uses) so
+ * there's exactly one ISO-parsing implementation in the codebase, not two.
  */
-export const VALID_FIELD_TYPES = ["string", "number", "integer", "boolean", "array", "object", "reference"] as const;
+export const VALID_FIELD_TYPES = ["string", "number", "integer", "boolean", "array", "object", "reference", "date"] as const;
 
 /**
- * Validate that a field's declared `type` is one of the six recognized
+ * Validate that a field's declared `type` is one of the recognized
  * values (vault#555). Returns `null` when `type` is unset (own-field checks
  * elsewhere already treat an unset type as "nothing to check against") or
  * recognized; otherwise a {@link TagFieldViolation} with `reason:
@@ -328,7 +336,7 @@ export function collectOwnFieldDefaultAndTypeViolations(
   return violations;
 }
 
-/** Same seven-type vocabulary as `TagFieldSchema.type`'s doc comment. Unknown/unset types pass (nothing to check against). */
+/** Same eight-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":
@@ -348,6 +356,13 @@ function defaultMatchesType(value: unknown, type: string): boolean {
     // VALID_FIELD_TYPES's doc comment.
     case "reference":
       return typeof value === "string";
+    // `date` accepts an ISO-8601 date (`YYYY-MM-DD`) or full RFC3339
+    // timestamp — the SAME grammar `date_filter`'s `updated_at` bound
+    // parses (`timestampToMs`, imported from cursor.ts), not a second,
+    // independently-drifting date parser. See VALID_FIELD_TYPES's doc
+    // comment.
+    case "date":
+      return typeof value === "string" && timestampToMs(value) !== null;
     default:
       return true;
   }
@@ -767,7 +782,7 @@ export function collectTagFieldViolations(
         violations.push({
           field: fieldName,
           reason: "unsupported_indexed_type",
-          message: `field "${fieldName}" has unsupported type "${spec.type}" for indexing (supported: string, integer, boolean, reference)`,
+          message: `field "${fieldName}" has unsupported type "${spec.type}" for indexing (supported: string, integer, boolean, reference, date)`,
         });
       } else {
         try {

package/core/src/types.ts

@@ -450,7 +450,7 @@ export interface Store {
    */
   getNoteByPath(path: string, extension?: string): Promise<Note | null>;
   getNotes(ids: string[]): Promise<Note[]>;
-  updateNote(id: string, updates: { content?: string; append?: string; prepend?: string; path?: string; extension?: string; metadata?: Record<string, unknown>; created_at?: string; skipUpdatedAt?: boolean; actor?: string | null; via?: string | null; if_updated_at?: string }): Promise<Note>;
+  updateNote(id: string, updates: { content?: string; append?: string; prepend?: string; path?: string; extension?: string; metadata?: Record<string, unknown>; created_at?: string; skipUpdatedAt?: boolean; actor?: string | null; via?: string | null; if_updated_at?: string; tagsForSchemaResolution?: string[] }): Promise<Note>;
   /**
    * Set a note's `created_at` and `updated_at` explicitly. Import-only:
    * used by the portable-md round-trip path to restore timestamps from

package/package.json

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

package/src/contract-errors.test.ts

@@ -315,7 +315,7 @@ describe("contract: error taxonomy — #554 (flipped from todo)", () => {
     expect(record?.fields ?? null).toBeFalsy();
   });
 
-  // Positive control — every one of the seven recognized types (indexable or
+  // Positive control — every one of the recognized types (indexable or
   // not) is accepted without complaint.
   it("REST PUT /api/tags/:name accepts every recognized field type", async () => {
     const req = new Request("http://localhost/api/tags/widget", {
@@ -329,6 +329,7 @@ describe("contract: error taxonomy — #554 (flipped from todo)", () => {
           e: { type: "array" },
           f: { type: "object" },
           g: { type: "reference" },
+          h: { type: "date" },
         },
       }),
     });