@openparachute/vault 0.6.3 → 0.6.4-rc.10

package/core/src/schema-defaults.ts

@@ -60,6 +60,33 @@ export interface SchemaField {
   type?: "string" | "number" | "integer" | "boolean" | "array" | "object";
   enum?: string[];
   description?: string;
+  /**
+   * Strict enforcement opt-in (vault#299, Part A). Default `false` — when
+   * unset/false, ALL constraints on this field are advisory: violations
+   * surface as `validation_status` warnings and the write succeeds (the
+   * historical byte-identical behavior). When `true`, ALL declared
+   * constraints on this field (type + enum + required + cardinality) flip
+   * to hard write rejections, all-or-nothing per field (the Gitcoin team's
+   * call — "enum + required together, not enum alone"). Free-form fields
+   * (`notes`/`description`) on an otherwise-strict tag stay advisory by
+   * simply leaving `strict` off — strictness is per-field, not per-tag.
+   */
+  strict?: boolean;
+  /**
+   * Whether the field MUST be present (and non-null) on a note carrying this
+   * tag. Advisory under `strict:false` (a `required` violation surfaces as a
+   * `missing_required` warning); a hard rejection only when `strict:true`.
+   */
+  required?: boolean;
+  /**
+   * Cardinality constraint for the field's value. `"one"` (the implicit
+   * default) means a single scalar — an array value is a `cardinality`
+   * violation. `"many"` means the value must be an array. Advisory under
+   * `strict:false`; a hard rejection when `strict:true`. Distinct from the
+   * relationship cardinality vocabulary (that governs typed links, not
+   * metadata fields).
+   */
+  cardinality?: "one" | "many";
 }
 
 /**
@@ -83,19 +110,35 @@ export interface ValidationWarning {
   /**
    * `type_mismatch` — value's type contradicts the declared `type`.
    * `enum_mismatch` — string value not in the declared `enum`.
+   * `missing_required` — a `required` field is absent or null (vault#299).
+   * `cardinality_mismatch` — value's shape (scalar vs array) contradicts the
+   *   declared `cardinality` (vault#299).
    * `schema_conflict` — two ancestors declared the same field with
    * different specs; first-in-walk wins, the loser surfaces here so the
    * operator can resolve the disagreement.
    */
-  reason: "type_mismatch" | "enum_mismatch" | "schema_conflict";
+  reason:
+    | "type_mismatch"
+    | "enum_mismatch"
+    | "missing_required"
+    | "cardinality_mismatch"
+    | "schema_conflict";
   message: string;
   /**
    * `schema_conflict` only — the tag whose declaration was overridden. Set
-   * when `reason === "schema_conflict"`; absent on type/enum mismatches.
+   * when `reason === "schema_conflict"`; absent on other reasons.
    * Surfaces structurally so agents don't have to regex `message` to find
    * the loser.
    */
   loser_schema?: string;
+  /**
+   * `true` when this violation comes from a `strict:true` field (vault#299).
+   * A strict violation is an ENFORCEMENT error — the write path rejects it.
+   * Absent/false for advisory warnings (the historical guidance behavior).
+   * Surfaced structurally so the write path can split "block" from "warn"
+   * without re-deriving the field's strict flag.
+   */
+  strict?: boolean;
 }
 
 export interface ValidationStatus {
@@ -126,6 +169,9 @@ 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.strict === true) field.strict = true;
+    if (f.required === true) field.required = true;
+    if (f.cardinality === "one" || f.cardinality === "many") field.cardinality = f.cardinality;
     fields[k] = field;
   }
   return fields;
@@ -301,15 +347,23 @@ function valueMatchesType(value: unknown, type: SchemaField["type"]): boolean {
  * Validate a note's metadata against the merged schema. Returns null when no
  * ancestor declares any fields (so the caller can omit `validation_status`
  * entirely). Otherwise returns the status with conflict warnings prepended,
- * followed by per-field type/enum mismatches.
+ * followed by per-field violations.
  *
  * Rules per merged field:
+ * - `required` declared and value absent/null → `missing_required`
  * - Present and `type` declared and value's type doesn't match → `type_mismatch`
  * - Present and `enum` declared and value not in enum → `enum_mismatch`
+ * - Present and `cardinality` declared and shape (scalar vs array) wrong
+ *   → `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).
  *
- * Fields not declared by any ancestor's schema are ignored entirely (this
- * isn't a "strict" validator — it's a guide). There is no `required` concept
- * (post-v17); declarations are advisory only.
+ * Fields not declared by any ancestor's schema are ignored entirely.
  */
 export function validateNote(
   resolved: ResolvedSchemas,
@@ -322,9 +376,25 @@ export function validateNote(
   const warnings: ValidationWarning[] = [...resolution.conflicts];
 
   for (const [fieldName, { spec, sourceTag }] of resolution.mergedFields) {
-    if (!(fieldName in m)) continue;
-    const value = m[fieldName];
-    if (value === undefined || value === null) continue;
+    const strictFlag = spec.strict === true ? { strict: true } : {};
+    const present = fieldName in m;
+    const value = present ? m[fieldName] : undefined;
+    const absent = !present || value === undefined || value === null;
+
+    if (spec.required === true && absent) {
+      warnings.push({
+        field: fieldName,
+        schema: sourceTag,
+        reason: "missing_required",
+        message: `'${fieldName}' is required (tag '${sourceTag}')`,
+        ...strictFlag,
+      });
+      // A required field that's absent has no value to type/enum/cardinality
+      // check — the missing_required violation stands alone.
+      continue;
+    }
+
+    if (absent) continue;
 
     if (spec.type && !valueMatchesType(value, spec.type)) {
       warnings.push({
@@ -332,6 +402,7 @@ export function validateNote(
         schema: sourceTag,
         reason: "type_mismatch",
         message: `'${fieldName}' should be ${spec.type} (tag '${sourceTag}')`,
+        ...strictFlag,
       });
     }
 
@@ -341,9 +412,91 @@ export function validateNote(
         schema: sourceTag,
         reason: "enum_mismatch",
         message: `'${fieldName}' must be one of [${spec.enum.join(", ")}] (tag '${sourceTag}')`,
+        ...strictFlag,
       });
     }
+
+    if (spec.cardinality) {
+      const isArray = Array.isArray(value);
+      const wantMany = spec.cardinality === "many";
+      if (wantMany !== isArray) {
+        warnings.push({
+          field: fieldName,
+          schema: sourceTag,
+          reason: "cardinality_mismatch",
+          message: wantMany
+            ? `'${fieldName}' must be an array (cardinality 'many', tag '${sourceTag}')`
+            : `'${fieldName}' must be a single value, not an array (cardinality 'one', tag '${sourceTag}')`,
+          ...strictFlag,
+        });
+      }
+    }
   }
 
   return { schemas: resolution.effectiveTags, warnings };
 }
+
+// ---------------------------------------------------------------------------
+// Strict enforcement (vault#299)
+// ---------------------------------------------------------------------------
+
+/**
+ * Thrown by the write path when a note violates one or more `strict:true`
+ * field constraints. Carries ALL per-field violations in a single error (the
+ * settled design lead — one `SchemaValidationError`, not per-axis errors), so
+ * an agent sees the whole contract it broke in one response and can fix every
+ * field before retrying.
+ *
+ * Each entry is a `ValidationWarning` with `strict: true`. `code` is stable
+ * (`SCHEMA_VALIDATION`) for transport mapping (MCP error / HTTP 422).
+ */
+export class SchemaValidationError extends Error {
+  code = "SCHEMA_VALIDATION" as const;
+  violations: ValidationWarning[];
+
+  constructor(violations: ValidationWarning[]) {
+    const summary = violations
+      .map((v) => `${v.field}: ${v.reason}`)
+      .join("; ");
+    super(`schema_validation: ${violations.length} strict field violation(s) — ${summary}`);
+    this.name = "SchemaValidationError";
+    this.violations = violations;
+  }
+}
+
+/**
+ * Extract the enforcement-level (strict) subset of a validation status —
+ * the violations the write path must reject. Conflict warnings are advisory
+ * by nature (they describe operator schema disagreements, not note data) and
+ * are never enforced even when a field is strict. Returns `[]` when nothing
+ * strict was violated (the common case — the caller then proceeds with the
+ * write).
+ */
+export function strictViolations(status: ValidationStatus | null): ValidationWarning[] {
+  if (!status) return [];
+  return status.warnings.filter((w) => w.strict === true && w.reason !== "schema_conflict");
+}
+
+/**
+ * Validate-and-enforce: run `validateNote`, and if any `strict:true` field is
+ * violated, throw a single `SchemaValidationError` carrying every violation.
+ * Returns the full advisory `ValidationStatus` (or null) on success so the
+ * caller can still surface advisory warnings on the response. `bypass: true`
+ * skips the throw entirely (migration-bypass scope) — the caller is
+ * responsible for logging the bypass.
+ *
+ * The write path calls this BEFORE persisting so a rejection leaves the note
+ * untouched.
+ */
+export function enforceStrictSchema(
+  resolved: ResolvedSchemas,
+  note: { path?: string | null; tags?: string[]; metadata?: Record<string, unknown> },
+  opts?: { bypass?: boolean },
+): { status: ValidationStatus | null; violations: ValidationWarning[] } {
+  const status = validateNote(resolved, note);
+  const violations = strictViolations(status);
+  if (violations.length > 0 && opts?.bypass !== true) {
+    throw new SchemaValidationError(violations);
+  }
+  return { status, violations };
+}

package/core/src/schema.ts

@@ -2,7 +2,7 @@ import { Database } from "bun:sqlite";
 import { normalizePath } from "./paths.js";
 import { rebuildIndexes } from "./indexed-fields.js";
 
-export const SCHEMA_VERSION = 22;
+export const SCHEMA_VERSION = 23;
 
 export const SCHEMA_SQL = `
 -- Notes: the universal record.
@@ -13,6 +13,17 @@ export const SCHEMA_SQL = `
 -- column; on-disk uniqueness key is (path, extension). See
 -- core/src/portable-md.ts:supportsInlineFrontmatter for the
 -- frontmatter-vs-sidecar split.
+--
+-- Write-attribution (v23, vault#298) — two axes of provenance, both nullable:
+--   created_by / created_via        — the principal + interface of the FIRST
+--                                     write (set once at create; never rewritten).
+--   last_updated_by / last_updated_via — the principal + interface of the MOST
+--                                     RECENT write (set on every mutating update).
+-- The *_by columns are the actor (a JWT sub, or an operator/token label for
+-- non-JWT auth); the *_via columns are the channel the write arrived through
+-- (mcp, surface:NAME, agent:ID, operator/cli, api). Legacy rows stay NULL —
+-- we don't fabricate authors for writes that predate attribution. See
+-- migrateToV23.
 CREATE TABLE IF NOT EXISTS notes (
   id TEXT PRIMARY KEY,
   content TEXT DEFAULT '',
@@ -20,7 +31,11 @@ CREATE TABLE IF NOT EXISTS notes (
   metadata TEXT DEFAULT '{}',
   created_at TEXT NOT NULL,
   updated_at TEXT,
-  extension TEXT NOT NULL DEFAULT 'md'
+  extension TEXT NOT NULL DEFAULT 'md',
+  created_by TEXT,
+  created_via TEXT,
+  last_updated_by TEXT,
+  last_updated_via TEXT
 );
 
 -- Tags: first-class identity carrying schema, hierarchy, and typed-link
@@ -479,6 +494,13 @@ export function initSchema(db: Database): void {
   // scans. See the 2026-06-10 query-perf measurements.
   migrateToV22(db);
 
+  // Migrate v22 → v23: write-attribution columns on `notes`
+  // (created_by/created_via/last_updated_by/last_updated_via) + their indexes.
+  // All four nullable; existing rows backfill to NULL ("written before
+  // attribution" — we don't fabricate authors for legacy writes). See
+  // vault#298.
+  migrateToV23(db);
+
   // Rebuild any generated columns + indexes declared in indexed_fields.
   // No-op for a fresh vault; idempotent on existing vaults.
   rebuildIndexes(db);
@@ -1150,6 +1172,43 @@ function migrateToV22(db: Database): void {
   db.exec("CREATE INDEX IF NOT EXISTS idx_notes_updated ON notes(updated_at, id)");
 }
 
+/**
+ * Migrate v22 → v23: per-identity + per-interface write attribution
+ * (vault#298). Adds four nullable columns to `notes` and an index on each so
+ * "what did Mathilda write" / "what came in via the meeting-ingest surface"
+ * are indexed lookups, not scans:
+ *
+ *   created_by        — principal (actor) of the first write
+ *   created_via       — interface/channel of the first write
+ *   last_updated_by   — principal of the most recent write
+ *   last_updated_via  — interface/channel of the most recent write
+ *
+ * `*_by` is the JWT `sub` (or an operator / `token:<id>` label for non-JWT
+ * auth); `*_via` is the channel (`mcp`, `surface:<name>`, `agent:<id>`,
+ * `operator`/`cli`, `api`). All four NULL on legacy rows — we deliberately do
+ * NOT backfill an author for writes that predate attribution; NULL reads as
+ * "unknown / pre-attribution," distinct from any real principal.
+ *
+ * Columns live here (not SCHEMA_SQL's index block) following the
+ * idx_tokens_vault_name / idx_notes_updated precedent: SCHEMA_SQL runs before
+ * the migration steps, so an upgrading v22 vault doesn't yet have the columns
+ * when that block evaluates. Fresh vaults get the columns from the CREATE
+ * TABLE above and the indexes from this same path. All idempotent — the
+ * column-existence guard + CREATE INDEX IF NOT EXISTS make re-runs no-ops.
+ */
+function migrateToV23(db: Database): void {
+  if (!hasTable(db, "notes")) return;
+  const cols = ["created_by", "created_via", "last_updated_by", "last_updated_via"];
+  for (const col of cols) {
+    if (!hasColumn(db, "notes", col)) {
+      db.exec(`ALTER TABLE notes ADD COLUMN ${col} TEXT`);
+    }
+  }
+  for (const col of cols) {
+    db.exec(`CREATE INDEX IF NOT EXISTS idx_notes_${col} ON notes(${col})`);
+  }
+}
+
 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/store.ts

@@ -100,7 +100,7 @@ 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 }): Promise<Note> {
+  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> {
     const note = noteOps.createNote(this.db, content, opts);
 
     if (content) {
@@ -140,6 +140,9 @@ export class BunSqliteStore implements Store {
       metadata?: Record<string, unknown>;
       created_at?: string;
       skipUpdatedAt?: boolean;
+      // Write-attribution (vault#298) — principal + interface of this edit.
+      actor?: string | null;
+      via?: string | null;
       if_updated_at?: string;
     },
   ): Promise<Note> {
@@ -628,36 +631,65 @@ export class BunSqliteStore implements Store {
     const priorRecord =
       patch.fields !== undefined ? tagSchemaOps.getTagRecord(this.db, tag) : null;
 
-    const result = tagSchemaOps.upsertTagRecord(this.db, tag, patch);
-
+    const indexedSet = (fields: Record<string, tagSchemaOps.TagFieldSchema> | null | undefined) =>
+      new Set(
+        Object.entries(fields ?? {})
+          .filter(([, v]) => v.indexed === true)
+          .map(([k]) => k),
+      );
+    const nextFields = patch.fields; // object | null | undefined
+    const priorIndexed = indexedSet(priorRecord?.fields);
+    const nextIndexed = indexedSet(nextFields);
+
+    // PRE-VALIDATE every newly-indexed field BEFORE any persistence. A bad
+    // field name (or unmappable type) must fail closed — the schema record
+    // must NOT be written when the backing index can't be created. Pre-checking
+    // here, before the transaction even opens, turns the failure into a clean
+    // caller error (IndexedFieldError → 400) and leaves the schema untouched.
+    // Without this, the prior code persisted the field declaration, THEN threw
+    // on declareField — a 500 plus a tag claiming an index the engine can't
+    // build (the "lying schema" loop). See vault#478.
     if (patch.fields !== undefined) {
-      const indexedSet = (fields: Record<string, tagSchemaOps.TagFieldSchema> | null | undefined) =>
-        new Set(
-          Object.entries(fields ?? {})
-            .filter(([, v]) => v.indexed === true)
-            .map(([k]) => k),
-        );
-      const nextFields = patch.fields; // object | null
-      const priorIndexed = indexedSet(priorRecord?.fields);
-      const nextIndexed = indexedSet(nextFields);
       for (const fieldName of nextIndexed) {
         const spec = nextFields![fieldName]!;
         const mapped = indexedFieldOps.mapFieldType(spec.type);
-        // Unmappable type for indexing is a caller error; surface it rather
-        // than silently skipping. MCP/REST validate up-front for a cleaner
-        // message, but this is the backstop at the chokepoint.
         if (!mapped) {
           throw new indexedFieldOps.IndexedFieldError(
             `field "${fieldName}" has unsupported type "${spec.type}" for indexing (supported: string, integer, boolean)`,
           );
         }
-        indexedFieldOps.declareField(this.db, fieldName, mapped, tag);
+        // Throws IndexedFieldError on an invalid identifier (e.g. kebab-case).
+        indexedFieldOps.validateFieldName(fieldName);
       }
-      for (const fieldName of priorIndexed) {
-        if (!nextIndexed.has(fieldName)) {
-          indexedFieldOps.releaseField(this.db, fieldName, tag);
+    }
+
+    // Persist the record + reconcile the indexed-field lifecycle atomically.
+    // If declareField throws inside the transaction (e.g. a cross-tag type
+    // mismatch only detectable once the existing declarer set is consulted),
+    // the whole write rolls back — the schema never ends up claiming an index
+    // that doesn't exist. vault#478 transactional fix.
+    let result: tagSchemaOps.TagRecord;
+    this.db.exec("BEGIN IMMEDIATE");
+    try {
+      result = tagSchemaOps.upsertTagRecord(this.db, tag, patch);
+
+      if (patch.fields !== undefined) {
+        for (const fieldName of nextIndexed) {
+          const spec = nextFields![fieldName]!;
+          // Type already validated above; non-null assertion is safe here.
+          const mapped = indexedFieldOps.mapFieldType(spec.type)!;
+          indexedFieldOps.declareField(this.db, fieldName, mapped, tag);
+        }
+        for (const fieldName of priorIndexed) {
+          if (!nextIndexed.has(fieldName)) {
+            indexedFieldOps.releaseField(this.db, fieldName, tag);
+          }
         }
       }
+      this.db.exec("COMMIT");
+    } catch (err) {
+      this.db.exec("ROLLBACK");
+      throw err;
     }
 
     if (patch.parent_names !== undefined) {

package/core/src/tag-schemas.ts

@@ -30,6 +30,18 @@ export interface TagFieldSchema {
   // across declarers — all tags declaring this field must agree on both
   // `type` and `indexed`. See core/src/indexed-fields.ts for lifecycle.
   indexed?: boolean;
+  // Strict-enforcement opt-in (vault#299). Default false (advisory). When
+  // true, ALL declared constraints on this field (type + enum + required +
+  // cardinality) flip from validation_status warnings to hard write
+  // rejections — all-or-nothing per field. Stored verbatim in the `fields`
+  // JSON column; the resolver (schema-defaults.ts) interprets it.
+  strict?: boolean;
+  // The field must be present + non-null on a note carrying this tag.
+  // Advisory unless `strict:true`. vault#299.
+  required?: boolean;
+  // "one" (scalar, default) or "many" (array). Advisory unless `strict:true`.
+  // Distinct from relationship cardinality. vault#299.
+  cardinality?: "one" | "many";
 }
 
 /**

package/core/src/triggers-store.ts

@@ -27,6 +27,12 @@ export interface StoredTriggerWhen {
   has_content?: boolean;
   missing_metadata?: string[];
   has_metadata?: string[];
+  /**
+   * Value-matched metadata predicate (vault#299 Part B). field →
+   * operator-object, evaluated with the shared query-operators engine. See
+   * src/config.ts:TriggerWhen.metadata.
+   */
+  metadata?: Record<string, Record<string, unknown>>;
 }
 
 /** Webhook auth — only the bearer-JWT path for now. */

package/core/src/types.ts

@@ -2,6 +2,7 @@ import type { Database } from "bun:sqlite";
 import type { TagFieldSchema, TagRelationship, TagRelationshipMap, TagRecord } from "./tag-schemas.js";
 import type { PrunedField } from "./indexed-fields.js";
 import type { TagExpandMode } from "./tag-hierarchy.js";
+import type { ValidationStatus } from "./schema-defaults.js";
 
 // ---- Re-exports ----
 
@@ -26,6 +27,19 @@ export interface Note {
   metadata?: Record<string, unknown>;
   createdAt: string; // ISO-8601
   updatedAt?: string;
+  /**
+   * Write-attribution (vault#298) — two axes of provenance, both nullable.
+   * `*By` is the principal (a JWT `sub`, or an operator / `token:<id>` label);
+   * `*Via` is the interface the write arrived through (`mcp`, `surface:<name>`,
+   * `agent:<id>`, `operator`/`cli`, `api`). The `created*` pair is set once at
+   * create; the `lastUpdated*` pair tracks the most recent mutating write. NULL
+   * = unknown / written before attribution existed (legacy rows) or by a path
+   * that carried no context — distinct from any real principal.
+   */
+  createdBy?: string | null;
+  createdVia?: string | null;
+  lastUpdatedBy?: string | null;
+  lastUpdatedVia?: string | null;
   tags?: string[];
   links?: Link[];
   /**
@@ -125,6 +139,15 @@ export interface QueryOpts {
   // for the field. Operator queries require the field to be declared
   // `indexed: true` in a tag schema; undeclared fields error loudly.
   metadata?: Record<string, unknown>;
+  // Write-attribution filters (vault#298). Exact-match on the indexed
+  // attribution columns — "what did Mathilda write" (`createdBy`/`lastUpdatedBy`)
+  // or "what came in via the meeting-ingest surface"
+  // (`createdVia`/`lastUpdatedVia`). Each is an exact string match; multiple
+  // AND together with the rest of the filter set.
+  createdBy?: string;
+  lastUpdatedBy?: string;
+  createdVia?: string;
+  lastUpdatedVia?: string;
   // Legacy shorthand: filters on `n.created_at` (vault ingestion time).
   // Equivalent to `dateFilter: { field: "created_at", from, to }`. Kept
   // as the common path; specifying both this and `dateFilter` rejects.
@@ -206,6 +229,12 @@ export interface NoteIndex {
   extension?: string;
   createdAt: string;
   updatedAt?: string;
+  /** Write-attribution (vault#298) — carried on the lean shape too so "who
+   *  touched what" is answerable without re-fetching full content. See `Note`. */
+  createdBy?: string | null;
+  createdVia?: string | null;
+  lastUpdatedBy?: string | null;
+  lastUpdatedVia?: string | null;
   tags?: string[];
   metadata?: Record<string, unknown>;
   byteSize: number;
@@ -232,8 +261,10 @@ export interface Store {
    */
   readonly db: Database;
 
-  // Notes
-  createNote(content: string, opts?: { id?: string; path?: string; tags?: string[]; metadata?: Record<string, unknown>; created_at?: string; extension?: string }): Promise<Note>;
+  // Notes. `actor` / `via` carry write-attribution (vault#298) — the
+  // principal + interface stamped onto created_by/created_via (and mirrored
+  // into the last_updated_* pair on create). Omitted → attribution NULL.
+  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>;
   getNote(id: string): Promise<Note | null>;
   /**
    * Look up a note by path. Pass `extension` to disambiguate when
@@ -244,7 +275,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; 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 }): 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
@@ -390,17 +421,7 @@ export interface Store {
   // `_default` is the implicit universal parent. Returns null when no
   // ancestor declares any fields. The underlying resolver is in-memory after
   // the first lazy load.
-  validateNoteAgainstSchemas(note: { path?: string | null; tags?: string[]; metadata?: Record<string, unknown> }): {
-    schemas: string[];
-    warnings: {
-      field: string;
-      schema: string;
-      reason: "type_mismatch" | "enum_mismatch" | "schema_conflict";
-      message: string;
-      /** Set only on `schema_conflict` — the tag whose declaration was overridden. */
-      loser_schema?: string;
-    }[];
-  } | null;
+  validateNoteAgainstSchemas(note: { path?: string | null; tags?: string[]; metadata?: Record<string, unknown> }): ValidationStatus | null;
 
   // Attachments
   addAttachment(noteId: string, path: string, mimeType: string, metadata?: Record<string, unknown>): Promise<Attachment>;

package/core/src/vault-projection.ts

@@ -369,6 +369,25 @@ export function projectionToMarkdown(args: {
     lines.push(`- No indexed metadata fields.`);
   }
 
+  // Strict fields (vault#299): surface the enforced contract so an agent knows
+  // BEFORE writing which fields hard-reject on violation (not just warn).
+  // Derived from each schema tag's effective fields carrying `strict: true`.
+  const strictLines: string[] = [];
+  for (const t of projection.tags) {
+    const strictNames = Object.entries(t.effective_fields)
+      .filter(([, spec]) => (spec as { strict?: boolean }).strict === true)
+      .map(([name]) => name);
+    if (strictNames.length > 0) {
+      strictLines.push(`  - #${t.name}: ${strictNames.join(", ")}`);
+    }
+  }
+  if (strictLines.length > 0) {
+    lines.push(
+      `- Strict fields (writes that violate these are REJECTED, not just warned — enum/type/required/cardinality enforced):`,
+    );
+    lines.push(...strictLines);
+  }
+
   lines.push("");
   lines.push("## Querying");
   lines.push("");

package/package.json

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

package/src/admin-spa.test.ts

@@ -38,9 +38,22 @@ describe("isAdminSpaPath", () => {
     expect(isAdminSpaPath("/vault/work/admin/")).toBe(true);
     expect(isAdminSpaPath("/vault/work/admin/tokens")).toBe(true);
     expect(isAdminSpaPath("/vault/boulder/admin/assets/index.js")).toBe(true);
-    // Vault names with URL-safe punctuation should still match — the regex
-    // captures up to the next "/" so dashes / dots / digits all pass.
-    expect(isAdminSpaPath("/vault/my-vault.2/admin")).toBe(true);
+    // Canonical-charset names (lowercase alphanumerics + hyphen / underscore)
+    // match; dots are NOT canonical (see the vault#253 reject test below).
+    expect(isAdminSpaPath("/vault/my-vault_2/admin")).toBe(true);
+  });
+
+  test("vault#253: names outside the canonical charset do NOT match the mount", () => {
+    // The mount used to capture `[^/]+`, so a name hub can never manage
+    // (dots, @, unicode) still served the admin SPA. Aligning the mount to
+    // hub's VAULT_NAME_CHARSET_RE (`/^[a-z0-9_-]+$/`) makes a non-canonical
+    // name 404 — the same answer hub gives. No legitimately-created vault can
+    // carry these characters (cmdCreate / init / the env var all reject them
+    // via validateVaultName), so nothing reachable regresses.
+    expect(isAdminSpaPath("/vault/my.vault/admin")).toBe(false);
+    expect(isAdminSpaPath("/vault/vault@v2/admin")).toBe(false);
+    expect(isAdminSpaPath("/vault/Work/admin")).toBe(false); // uppercase isn't canonical
+    expect(isAdminSpaPath("/vault/🦑/admin")).toBe(false);
   });
 
   test("does not match adjacent paths under the same vault", () => {
@@ -111,8 +124,8 @@ describe("serveAdminSpa", () => {
     expect(cssRes.headers.get("content-type")).toContain("text/css");
   });
 
-  test("vault names with URL-safe punctuation strip cleanly", async () => {
-    const res = await serveAdminSpa(fixtureDir, "/vault/my-vault.2/admin/assets/index-abc.js");
+  test("canonical-charset vault names strip cleanly", async () => {
+    const res = await serveAdminSpa(fixtureDir, "/vault/my-vault_2/admin/assets/index-abc.js");
     expect(res.status).toBe(200);
     expect(res.headers.get("content-type")).toContain("application/javascript");
   });