hafez 1.2.0 → 1.4.0

package/dist/cli/upgrade.d.ts

@@ -0,0 +1,42 @@
+export type Comparison = 'behind' | 'equal' | 'ahead' | 'unknown';
+/** `command` entries are directly executable (after user approval); `action`
+ * entries are prose, so an agent that shells out every entry does not try to
+ * run English. */
+export interface UpgradeStep {
+    kind: 'command' | 'action';
+    text: string;
+}
+export interface UpgradeState {
+    current: string;
+    latest: string | null;
+    comparison: Comparison;
+    registryReachable: boolean;
+    npmMajor: number | null;
+    install: 'registry' | 'dev-checkout';
+    skill: 'present' | 'absent';
+    skillSource: string;
+    skillTarget: string;
+    /** Mutually exclusive with the registry install in `steps` — exposed
+     * separately so an agent iterating `steps` cannot run both. */
+    alternativeInstall: string | null;
+    steps: UpgradeStep[];
+}
+export interface UpgradeDeps {
+    fetch: typeof globalThis.fetch;
+    registryUrl: string;
+    packageRoot: string;
+    installedSkillPath: string;
+    npmVersion: () => string;
+}
+/** Three-way compare on the numeric segments. Hand-rolled string compare is
+ * the trap this exists to avoid: `1.10.0` < `1.9.0` lexicographically.
+ * Anything that is not plain X.Y.Z (a prerelease, a build tag) is `unknown` —
+ * this tool never guesses at a version it cannot order. */
+export declare function compareVersions(local: string, latest: string): Comparison;
+export declare function buildUpgradeState(deps: UpgradeDeps): Promise<UpgradeState>;
+export declare function renderUpgrade(state: UpgradeState): string;
+/** `deps` is the third parameter, unreachable from dispatch (PreVaultRun is
+ * `(args, ctx)`) — the tests inject it directly. */
+export declare function cmdUpgrade(args: string[], ctx: {
+    json: boolean;
+}, deps?: UpgradeDeps): Promise<string>;

package/dist/cli/upgrade.js

@@ -0,0 +1,305 @@
+// src/cli/upgrade.ts
+//
+// `hafez upgrade` — agent-directed update check. It CHECKS AND PRINTS; it
+// never installs. The printed steps install code and overwrite the user's
+// agent instructions, so the privileged step is the human's — same discipline
+// as `onboard` (writes nothing outside the vault) and as the release skill
+// (`npm publish` is the user's action). It also sidesteps a process replacing
+// its own binary mid-run.
+//
+// `pre-vault` on purpose: it must still work when the vault is unresolvable
+// or the native SQLite binding is unbuilt, which is exactly when someone is
+// trying to upgrade. Nothing here touches the core.
+//
+// Untrusted input: the registry response is rendered into a document an agent
+// will execute commands from. Only the `version` field is read, only after it
+// matches plain X.Y.Z, and no caught error's message, cause, or stack ever
+// reaches stdout — `JSON.parse` embeds a slice of the offending body in its
+// message, so every failure branch renders a fixed string constant.
+import { execFileSync } from 'child_process';
+import { existsSync, readFileSync } from 'fs';
+import { homedir } from 'os';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+import { UsageError } from './args.js';
+import { INTEGRATION_SNIPPET } from './onboard.js';
+const PLAIN_SEMVER = /^\d+\.\d+\.\d+$/;
+const REGISTRY_TIMEOUT_MS = 3000;
+const NPM_PROBE_TIMEOUT_MS = 3000;
+const DEFAULT_REGISTRY_URL = 'https://registry.npmjs.org/hafez/latest';
+const DEV_CHECKOUT_WORK = 'git pull && npm run build && npm run install:local';
+const NPM_PROBE_NOTE = 'The local npm version could not be determined, so every install flag is included above. ' +
+    'npm majors that predate a flag print `npm warn Unknown cli config` and proceed — that warning is harmless.';
+const ETARGET_NOTE = 'If the install fails with ETARGET, your configured registry (a mirror or proxy) does not have the pinned version — ' +
+    'append `--registry=https://registry.npmjs.org` to the install command.';
+const VERIFY_NOTE = 'Re-run `hafez upgrade` to verify.';
+/** Three-way compare on the numeric segments. Hand-rolled string compare is
+ * the trap this exists to avoid: `1.10.0` < `1.9.0` lexicographically.
+ * Anything that is not plain X.Y.Z (a prerelease, a build tag) is `unknown` —
+ * this tool never guesses at a version it cannot order. */
+export function compareVersions(local, latest) {
+    if (!PLAIN_SEMVER.test(local) || !PLAIN_SEMVER.test(latest))
+        return 'unknown';
+    const a = local.split('.').map(Number);
+    const b = latest.split('.').map(Number);
+    for (let i = 0; i < 3; i++) {
+        if (a[i] < b[i])
+            return 'behind';
+        if (a[i] > b[i])
+            return 'ahead';
+    }
+    return 'equal';
+}
+/** A path that cannot be made safe by single-quoting it. Spaces, `$(`, and
+ * globs are all inert inside single quotes; a quote, newline, or control
+ * character is not. */
+function unquotable(path) {
+    return /['\u0000-\u001f]/.test(path);
+}
+function exists(path) {
+    try {
+        return existsSync(path);
+    }
+    catch {
+        return false;
+    }
+}
+/** The installed version, from our own package.json — trusted input, so it is
+ * echoed as-is. A non-plain version (a dev prerelease) still prints; it just
+ * makes the comparison `unknown`. */
+function readLocalVersion(packageRoot) {
+    try {
+        const parsed = JSON.parse(readFileSync(join(packageRoot, 'package.json'), 'utf-8'));
+        return typeof parsed?.version === 'string' && parsed.version.length > 0 ? parsed.version : 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+/** Reachability and parseability are different facts, so they get different
+ * statuses: no usable answer at all (transport failure, timeout, non-2xx, or
+ * an unparseable body) is `reachable: false`; a parsed answer whose `version`
+ * is not plain X.Y.Z is `reachable: true` with a null latest. Both print no
+ * install command — there is no verified version to pin. The `reachable:
+ * false` message covers the mirror-404 case too, so it does not claim the
+ * user is offline when the registry answered. */
+async function checkRegistry(deps) {
+    try {
+        const res = await deps.fetch(deps.registryUrl, { signal: AbortSignal.timeout(REGISTRY_TIMEOUT_MS) });
+        if (!res.ok)
+            return { latest: null, reachable: false };
+        const body = (await res.json());
+        const version = body?.version;
+        if (typeof version !== 'string' || !PLAIN_SEMVER.test(version))
+            return { latest: null, reachable: true };
+        return { latest: version, reachable: true };
+    }
+    catch {
+        // Deliberately discards the caught value: its message can carry a slice of
+        // the response body straight into an agent's execution context.
+        return { latest: null, reachable: false };
+    }
+}
+function probeNpmMajor(deps) {
+    try {
+        const major = Number(deps.npmVersion().trim().split('.')[0]);
+        return Number.isInteger(major) && major > 0 ? major : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The dev-checkout upgrade runs git and npm scripts, so it MUST name its
+ * directory: an agent's cwd is the user's own project, not this checkout, and
+ * a bare `git pull && npm run build` would upgrade whatever repo it happens to
+ * be standing in. */
+function devCheckoutStep(packageRoot) {
+    if (unquotable(packageRoot)) {
+        return {
+            kind: 'action',
+            text: `Upgrade the development checkout at ${packageRoot} by hand — its path contains characters that single-quoting cannot make safe. In that directory run: ${DEV_CHECKOUT_WORK}`,
+        };
+    }
+    return { kind: 'command', text: `cd '${packageRoot}' && ${DEV_CHECKOUT_WORK}` };
+}
+function skillCopyStep(source, target, sourceExists) {
+    if (!sourceExists) {
+        // Emitting the cp anyway would hand the agent a step that fails with
+        // ENOENT and reads as a failed upgrade, for a check that found nothing.
+        return {
+            kind: 'action',
+            text: `No bundled skill at ${source}, so the installed copy at ${target} cannot be refreshed from this ` +
+                'package. Re-copy it from the installed hafez package after upgrading — see the README Updating section.',
+        };
+    }
+    if (unquotable(source) || unquotable(target)) {
+        return {
+            kind: 'action',
+            text: 'Copy the bundled skill file over the installed one by hand — the paths contain characters ' +
+                `that single-quoting cannot make safe. Source: ${source} — Target: ${target}`,
+        };
+    }
+    return { kind: 'command', text: `mkdir -p '${dirname(target)}' && cp '${source}' '${target}'` };
+}
+/** The action list, in execution order. Every command is built from static
+ * constants; the only interpolated values are the regex-validated version and
+ * the quoted absolute paths (package root, skill source, skill target). */
+function deriveSteps(state, ctx) {
+    const steps = [];
+    let alternativeInstall = null;
+    const upgrading = state.comparison === 'behind' && state.latest !== null;
+    if (upgrading) {
+        if (state.install === 'dev-checkout') {
+            // A contributor whose ~/.local/bin/hafez symlinks into a source tree
+            // would have the symlink shadow any global install forever — and the
+            // mandatory re-run would report `behind` forever with it.
+            steps.push(devCheckoutStep(ctx.packageRoot));
+        }
+        else {
+            // Pinned, never `@latest`: an unpinned command resolves at install time
+            // and can install something other than what was just verified.
+            const scripts = state.npmMajor === null || state.npmMajor >= 11 ? ' --allow-scripts=better-sqlite3' : '';
+            const remote = state.npmMajor === null || state.npmMajor >= 12 ? ' --allow-remote=root' : '';
+            steps.push({ kind: 'command', text: `npm install -g hafez@${state.latest}${scripts}` });
+            // Same package, same install scripts — the tarball needs the scripts flag too.
+            alternativeInstall =
+                `npm install -g https://github.com/shrvn-r/hafez/releases/download/v${state.latest}/hafez.tgz${scripts}${remote}`;
+            if (state.npmMajor === null)
+                steps.push({ kind: 'action', text: NPM_PROBE_NOTE });
+            steps.push({ kind: 'action', text: ETARGET_NOTE });
+        }
+    }
+    // Unconditional when the skill exists: the bundled skill ships INSIDE the
+    // installed package, so on the main upgrade path the bundled copy is equally
+    // stale and any byte-compare reports "current" in exactly the silent-drift
+    // case detection would exist for. Copying an identical file is a no-op.
+    if (state.skill === 'present')
+        steps.push(skillCopyStep(state.skillSource, state.skillTarget, ctx.skillSourceExists));
+    // A SCHEMA_VERSION bump does not self-heal: the read-only path warns and
+    // returns null, so the first post-upgrade query answers *empty* until a
+    // write command or an explicit rebuild.
+    if (upgrading)
+        steps.push({ kind: 'command', text: 'hafez index rebuild' });
+    if (steps.length > 0)
+        steps.push({ kind: 'action', text: VERIFY_NOTE });
+    return { steps, alternativeInstall };
+}
+export async function buildUpgradeState(deps) {
+    const current = readLocalVersion(deps.packageRoot);
+    const registry = await checkRegistry(deps);
+    const base = {
+        current,
+        latest: registry.latest,
+        comparison: registry.latest === null ? 'unknown' : compareVersions(current, registry.latest),
+        registryReachable: registry.reachable,
+        npmMajor: probeNpmMajor(deps),
+        // Published tarballs carry only dist, skill, README.md and LICENSE.
+        install: exists(join(deps.packageRoot, 'src')) ? 'dev-checkout' : 'registry',
+        skill: exists(deps.installedSkillPath) ? 'present' : 'absent',
+        skillSource: join(deps.packageRoot, 'skill', 'SKILL.md'),
+        skillTarget: deps.installedSkillPath,
+    };
+    return {
+        ...base,
+        ...deriveSteps(base, { packageRoot: deps.packageRoot, skillSourceExists: exists(base.skillSource) }),
+    };
+}
+function versionLines(state) {
+    const lines = [`Installed version: ${state.current}`];
+    if (state.latest === null) {
+        lines.push(state.registryReachable
+            ? "Published version: unknown — the registry's answer is not a plain X.Y.Z. Check manually at https://www.npmjs.com/package/hafez."
+            : "Published version: couldn't check (offline?) — the registry gave no usable answer. If HAFEZ_REGISTRY_URL points at a mirror, it may simply not carry hafez. Nothing has changed.");
+        return lines;
+    }
+    lines.push(`Published version: ${state.latest}`);
+    if (state.comparison === 'behind')
+        lines.push('Your install is BEHIND the published version — steps below.');
+    else if (state.comparison === 'equal')
+        lines.push('Your install is current. Checked against the npm registry only — a just-cut GitHub Release may not be published yet.');
+    else if (state.comparison === 'ahead')
+        lines.push('Local build is ahead of the published version — nothing to do.');
+    else
+        lines.push('Could not compare: the installed version is not a plain X.Y.Z. Check manually.');
+    return lines;
+}
+export function renderUpgrade(state) {
+    const out = [
+        '# Hafez — Upgrade Check',
+        '',
+        'You are an agent reading this on behalf of your user. This command checks',
+        'and prints — it never installs anything. The steps below install code and',
+        "overwrite the user's agent instructions, so show them verbatim, get an",
+        'explicit yes, and only then run them. Never run them unattended.',
+        '',
+        '## Status',
+        '',
+        ...versionLines(state),
+    ];
+    if (state.install === 'dev-checkout') {
+        out.push('Install source: development checkout (this package has a src/ directory) — upgrade with git, not npm.');
+    }
+    out.push('');
+    out.push(state.skill === 'present'
+        ? `Skill: installed at ${state.skillTarget}. The skill ships inside the hafez package, so an upgraded package leaves this copy stale — the re-copy step is idempotent, run it either way.`
+        : `Skill: none at ${state.skillTarget} — nothing to re-copy (a non-Claude-Code harness, not drift).`);
+    out.push('');
+    out.push('Integration snippet — compare this against the Hafez section of the');
+    out.push("user's instructions file (Claude Code: ~/.claude/CLAUDE.md; any");
+    out.push('AGENTS.md harness: its global AGENTS.md) and reconcile differences');
+    out.push('with them. Do not rewrite their file unasked.');
+    out.push('');
+    out.push(INTEGRATION_SNIPPET);
+    out.push('');
+    out.push('## Steps');
+    out.push('');
+    if (state.steps.length === 0) {
+        out.push('Nothing to do.');
+        return out.join('\n') + '\n';
+    }
+    out.push('In this order, after the user approves:');
+    out.push('');
+    state.steps.forEach((step, i) => {
+        out.push(`${i + 1}. [${step.kind}] ${step.text}`);
+    });
+    if (state.alternativeInstall !== null) {
+        out.push('');
+        out.push('Alternative to the npm install above — ONLY if hafez was installed from');
+        out.push('the GitHub release tarball rather than the npm registry. Run one or the');
+        out.push('other, never both:');
+        out.push('');
+        out.push(`  ${state.alternativeInstall}`);
+    }
+    return out.join('\n') + '\n';
+}
+function defaultDeps() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    return {
+        fetch: (...args) => globalThis.fetch(...args),
+        // The documented escape hatch for private registries and proxied networks.
+        registryUrl: process.env.HAFEZ_REGISTRY_URL || DEFAULT_REGISTRY_URL,
+        packageRoot: join(here, '..', '..'),
+        installedSkillPath: join(homedir(), '.claude', 'skills', 'hafez', 'SKILL.md'),
+        // Bounded for the same reason the registry fetch is: a global prefix on a
+        // network mount or a cold cache can hang npm, and `upgrade` has to stay
+        // answerable when the environment is the thing that is broken. A timeout
+        // kills the probe, which degrades to npmMajor: null and every flag.
+        npmVersion: () => execFileSync('npm', ['--version'], {
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+            timeout: NPM_PROBE_TIMEOUT_MS,
+        }),
+    };
+}
+const USAGE = 'Usage: hafez upgrade [--json]';
+/** `deps` is the third parameter, unreachable from dispatch (PreVaultRun is
+ * `(args, ctx)`) — the tests inject it directly. */
+export async function cmdUpgrade(args, ctx, deps = defaultDeps()) {
+    for (const arg of args) {
+        if (arg.startsWith('--'))
+            throw new UsageError(`Unknown flag ${arg}\n${USAGE}`);
+        throw new UsageError(`upgrade takes no arguments\n${USAGE}`);
+    }
+    const state = await buildUpgradeState(deps);
+    return ctx.json ? JSON.stringify(state, null, 2) : renderUpgrade(state);
+}

package/dist/contracts.d.ts

@@ -1,3 +1,9 @@
+import type { KnowledgeSubtype } from './types.js';
+export declare const ENTITY_TYPES: readonly ["capture", "entity", "project"];
+export declare const ENTITY_STATUSES: readonly ["active", "paused", "done"];
+export declare const SESSION_LOG_TYPES: readonly ["progress", "decision", "blocker", "research"];
+export declare const CONFIDENCE_LEVELS: readonly ["observation", "pattern", "principle"];
+export declare const VALID_SUBTYPES: readonly ["insight", "plan"];
 export interface TypeContract {
     type: string;
     description: string;
@@ -12,15 +18,58 @@ export interface TypeContract {
 export declare const ALL_CONTRACTS: TypeContract[];
 export declare function getContract(type: string): TypeContract;
 export declare function hasCapability(type: string, section: string): boolean;
-import type { KnowledgeSubtype } from './types.js';
-export declare const ENTITY_TYPES: readonly ["capture", "entity", "project"];
-export declare const ENTITY_STATUSES: readonly ["active", "paused", "done"];
-export declare const SESSION_LOG_TYPES: readonly ["progress", "decision", "blocker", "research"];
-export declare const CONFIDENCE_LEVELS: readonly ["observation", "pattern", "principle"];
-export declare const VALID_SUBTYPES: readonly ["insight", "plan"];
+/** A knowledge note with no persisted subtype is an insight — the one place
+ * that default lives. Every consumer (templates, index rows, exports) reads
+ * it from here so classification can't drift between surfaces. */
+export declare const DEFAULT_KNOWLEDGE_SUBTYPE: "insight";
 export declare const ALIAS_KEYS: {
     readonly 'update.fields.insight': "synthesis";
     readonly 'create.knowledge.fields.insight': "synthesis";
     readonly 'create.session.fields.insight': "synthesis";
 };
 export declare const SUBTYPE_SECTIONS: Record<KnowledgeSubtype, string[]>;
+/** Sections whose content only ever grows — sync merges union their lines
+ * instead of letting the newer side replace the older (see merge.ts). */
+export declare const APPEND_ONLY_SECTIONS: ReadonlySet<string>;
+/** Session-file sections. Sessions have no TypeContract (they are not typed
+ * entities), but their headings are still structural for Document splitting. */
+export declare const SESSION_SECTIONS: readonly ["Summary", "Entities Touched", "Decisions"];
+/** Statuses a plan-subtype knowledge note may carry. Plans are tracked work
+ * with a lifecycle; the file validator and the mutation gate read this one
+ * tuple so they cannot drift. */
+export declare const PLAN_STATUSES: readonly ["active", "done"];
+/** Statuses by knowledge subtype. An empty list means `status` is not part of
+ * that subtype's contract at all — mutations setting it are rejected. */
+export declare const SUBTYPE_STATUSES: Record<KnowledgeSubtype, readonly string[]>;
+/** What a mutation is aimed at — enough to answer "does this document's
+ * contract have that field / that section?". Knowledge capabilities are
+ * subtype-level (plans and insights have different bodies and lifecycles),
+ * entity capabilities are type-level. */
+export type DocTarget = {
+    kind: 'entity';
+    type: string;
+} | {
+    kind: 'knowledge';
+    subtype?: KnowledgeSubtype;
+};
+/** Sections a document of this shape can carry — the one answer to "would
+ * text written into section X survive on this document?". */
+export declare function sectionsFor(target: DocTarget): string[];
+/** Statuses this document may carry. Empty ⇒ `status` is not a field of its
+ * contract, so setting it is a validation error. */
+export declare function statusesFor(target: DocTarget): readonly string[];
+/** Create-op fields that write their text into a named body section. The
+ * chosen template decides whether that section exists; when it doesn't, the
+ * text has nowhere to land, so the op is rejected (see `unreachableFields`).
+ * Update-op content fields are absent on purpose — `setSection` /
+ * `appendToSection` create a missing section, so update never loses text. */
+export declare const CREATE_FIELD_SECTIONS: Record<string, string>;
+/** Fields present in `fields` whose target section this document cannot hold.
+ * Policy is reject-never-route: text is never silently dropped and never
+ * redirected into a section the caller did not name. */
+export declare function unreachableFields(target: DocTarget, fields: Record<string, unknown>): Array<{
+    field: string;
+    section: string;
+}>;
+/** Human label for a target, used in every gate's error text. */
+export declare function describeTarget(target: DocTarget): string;

package/dist/contracts.js

@@ -1,24 +1,48 @@
+// --- Canonical enum tuples (single source of truth) ---
+// Every consumer (file validators, the Op Spec table, help renderer, and the
+// enum unions in types.ts) imports these — no other file may declare local
+// copies, and the contracts below are built out of them rather than beside
+// them.
+export const ENTITY_TYPES = ['capture', 'entity', 'project'];
+export const ENTITY_STATUSES = ['active', 'paused', 'done'];
+export const SESSION_LOG_TYPES = ['progress', 'decision', 'blocker', 'research'];
+export const CONFIDENCE_LEVELS = ['observation', 'pattern', 'principle'];
+// 'insight' is the subtype (frontmatter classification), 'Synthesis' is the section heading.
+// The rename was insight→synthesis for the section/field only; the subtype stays 'insight'.
+export const VALID_SUBTYPES = ['insight', 'plan'];
+/** The item frontmatter contract, shared by all three item types — they
+ * differ in sections and lifecycle, never in which fields are mandatory.
+ * schema.validateEntityFrontmatter enforces exactly this list (parity test in
+ * tests/contracts.test.ts). */
+const ITEM_REQUIRED = ['name', 'type', 'status', 'created', 'last-touched'];
+/** Optional frontmatter for the types that can sit in a hierarchy. A capture
+ * has not been triaged yet, so it carries neither links nor staleness. */
+const ITEM_OPTIONAL = ['domain', 'parent', 'related', 'tags', 'staleness-days'];
 const CAPTURE = {
     type: 'capture',
     description: 'Quick capture. A link, a thought, a bug report. No structure required — just get it in.',
     kind: 'item',
-    requiredFields: ['name', 'type', 'status', 'created', 'last-touched'],
+    requiredFields: ITEM_REQUIRED,
     optionalFields: ['domain', 'tags'],
-    validStatuses: ['active', 'done'],
+    // A capture is triage-stage: it is either open or dealt with, never paused.
+    validStatuses: ENTITY_STATUSES.filter(s => s !== 'paused'),
     defaultSections: ['Notes'],
     // Brief/Next Actions: the CLI never type-gated setBrief/addNextAction, so captures
     // carrying a delivery brief and actions are established practice — the contract
-    // follows observed behaviour (decided 2026-07-19).
-    optionalSections: ['Session Log', 'Brief', 'Next Actions'],
+    // follows observed behaviour (decided 2026-07-19). Current State likewise:
+    // update --current-state is kind-gated, not type-gated, so captures can carry
+    // it — omitting it here made the heading non-structural under the per-type
+    // Document binding and a later Brief rewrite silently deleted the section.
+    optionalSections: ['Session Log', 'Brief', 'Next Actions', 'Current State'],
     canPromoteTo: ['entity', 'project', 'knowledge'],
 };
 const ENTITY = {
     type: 'entity',
     description: 'Tracked work with substance. A bug, feature, decision, or task. The atomic unit of work.',
     kind: 'item',
-    requiredFields: ['name', 'type', 'status', 'created', 'last-touched'],
-    optionalFields: ['domain', 'parent', 'related', 'tags', 'staleness-days'],
-    validStatuses: ['active', 'paused', 'done'],
+    requiredFields: ITEM_REQUIRED,
+    optionalFields: ITEM_OPTIONAL,
+    validStatuses: [...ENTITY_STATUSES],
     defaultSections: ['Context', 'Session Log'],
     optionalSections: ['Brief', 'Next Actions', 'Current State'],
     canPromoteTo: ['project'],
@@ -27,9 +51,9 @@ const PROJECT = {
     type: 'project',
     description: 'Scoped effort with goals and deliverables. Can have children. Can be finite or perpetual.',
     kind: 'item',
-    requiredFields: ['name', 'type', 'status', 'created', 'last-touched'],
-    optionalFields: ['domain', 'parent', 'related', 'tags', 'staleness-days'],
-    validStatuses: ['active', 'paused', 'done'],
+    requiredFields: ITEM_REQUIRED,
+    optionalFields: ITEM_OPTIONAL,
+    validStatuses: [...ENTITY_STATUSES],
     defaultSections: ['Purpose', 'Goals', 'Session Log'],
     optionalSections: ['Brief', 'Next Actions', 'Current State', 'Open Questions'],
     canPromoteTo: [],
@@ -58,22 +82,26 @@ export function getContract(type) {
         throw new Error(`Unknown type: ${type}. Valid types: ${Object.keys(CONTRACT_MAP).join(', ')}`);
     return contract;
 }
-export function hasCapability(type, section) {
+/** Every section a type's contract declares, default and optional alike —
+ * the one place the two lists are concatenated (sectionsFor and hasCapability
+ * both answer from it). */
+function contractSections(type) {
     const contract = getContract(type);
-    return contract.defaultSections.includes(section) || contract.optionalSections.includes(section);
+    return [...contract.defaultSections, ...contract.optionalSections];
 }
-// --- Canonical enum tuples (single source of truth) ---
-// Every consumer (file validators, CLI input validator, help renderer) imports these.
-// The cli-schema-parity test enforces that no other file declares local copies.
-export const ENTITY_TYPES = ['capture', 'entity', 'project'];
-export const ENTITY_STATUSES = ['active', 'paused', 'done'];
-export const SESSION_LOG_TYPES = ['progress', 'decision', 'blocker', 'research'];
-export const CONFIDENCE_LEVELS = ['observation', 'pattern', 'principle'];
-// 'insight' is the subtype (frontmatter classification), 'Synthesis' is the section heading.
-// The rename was insight→synthesis for the section/field only; the subtype stays 'insight'.
-export const VALID_SUBTYPES = ['insight', 'plan'];
+export function hasCapability(type, section) {
+    return contractSections(type).includes(section);
+}
+/** A knowledge note with no persisted subtype is an insight — the one place
+ * that default lives. Every consumer (templates, index rows, exports) reads
+ * it from here so classification can't drift between surfaces. */
+export const DEFAULT_KNOWLEDGE_SUBTYPE = 'insight';
 // --- Alias table ---
-// Declared-alias fields that parseBatchInput normalizes to their canonical name.
+// Declared-alias fields, keyed by the op path they may appear on and mapped to
+// their canonical name. The Op Spec layer (normalizeAliases in batch-ops.ts)
+// normalizes them once, before validation, so every entry point applies the same
+// canonical op; an op path absent from this table (create.entity.fields.insight)
+// is the kind gate — the strict shape rejects the alias there.
 // schema-introspect cannot infer these from Zod alone (both are declared .optional()),
 // so rendering code reads this table to strip aliased keys from user-facing output.
 export const ALIAS_KEYS = {
@@ -85,3 +113,62 @@ export const SUBTYPE_SECTIONS = {
     insight: ['Synthesis', 'Evidence', 'Sources'],
     plan: ['Goal', 'Steps', 'Dependencies'],
 };
+/** Sections whose content only ever grows — sync merges union their lines
+ * instead of letting the newer side replace the older (see merge.ts). */
+export const APPEND_ONLY_SECTIONS = new Set(['Evidence', 'Sources']);
+/** Session-file sections. Sessions have no TypeContract (they are not typed
+ * entities), but their headings are still structural for Document splitting. */
+export const SESSION_SECTIONS = ['Summary', 'Entities Touched', 'Decisions'];
+/** Statuses a plan-subtype knowledge note may carry. Plans are tracked work
+ * with a lifecycle; the file validator and the mutation gate read this one
+ * tuple so they cannot drift. */
+export const PLAN_STATUSES = ['active', 'done'];
+/** Statuses by knowledge subtype. An empty list means `status` is not part of
+ * that subtype's contract at all — mutations setting it are rejected. */
+export const SUBTYPE_STATUSES = {
+    insight: [],
+    plan: PLAN_STATUSES,
+};
+/** Sections a document of this shape can carry — the one answer to "would
+ * text written into section X survive on this document?". */
+export function sectionsFor(target) {
+    if (target.kind === 'knowledge') {
+        return [...SUBTYPE_SECTIONS[target.subtype ?? DEFAULT_KNOWLEDGE_SUBTYPE]];
+    }
+    return contractSections(target.type);
+}
+/** Statuses this document may carry. Empty ⇒ `status` is not a field of its
+ * contract, so setting it is a validation error. */
+export function statusesFor(target) {
+    return target.kind === 'knowledge'
+        ? SUBTYPE_STATUSES[target.subtype ?? DEFAULT_KNOWLEDGE_SUBTYPE]
+        : getContract(target.type).validStatuses;
+}
+/** Create-op fields that write their text into a named body section. The
+ * chosen template decides whether that section exists; when it doesn't, the
+ * text has nowhere to land, so the op is rejected (see `unreachableFields`).
+ * Update-op content fields are absent on purpose — `setSection` /
+ * `appendToSection` create a missing section, so update never loses text. */
+export const CREATE_FIELD_SECTIONS = {
+    purpose: 'Purpose',
+    notes: 'Notes',
+    brief: 'Brief',
+    add_action: 'Next Actions',
+    add_actions: 'Next Actions',
+    synthesis: 'Synthesis',
+};
+/** Fields present in `fields` whose target section this document cannot hold.
+ * Policy is reject-never-route: text is never silently dropped and never
+ * redirected into a section the caller did not name. */
+export function unreachableFields(target, fields) {
+    const available = new Set(sectionsFor(target));
+    return Object.entries(CREATE_FIELD_SECTIONS)
+        .filter(([field, section]) => fields[field] !== undefined && !available.has(section))
+        .map(([field, section]) => ({ field, section }));
+}
+/** Human label for a target, used in every gate's error text. */
+export function describeTarget(target) {
+    return target.kind === 'entity'
+        ? `type '${target.type}'`
+        : `knowledge subtype '${target.subtype ?? DEFAULT_KNOWLEDGE_SUBTYPE}'`;
+}

package/dist/dates.d.ts

@@ -0,0 +1,10 @@
+/** The local calendar day as YYYY-MM-DD. The single source of "today". */
+export declare function localDay(d?: Date): string;
+/**
+ * Bare YYYY-MM-DD → local midnight, for git's approxidate. A date-only
+ * `--since` is otherwise filled with the *current* time of day ("since right
+ * now"), and any explicit instant must anchor to the same local day boundary
+ * the stamps and query comparisons use. Relative forms (`7.days.ago`) are
+ * already local and pass through untouched.
+ */
+export declare function normalizeSinceDate(since: string): string;

package/dist/dates.js

@@ -0,0 +1,27 @@
+// src/dates.ts
+// The vault's one calendar-day convention: the LOCAL day.
+//
+// A hafez vault is personal — "today" means the user's today, so every
+// surface that names a day (created / last-touched / session-log stamping,
+// the dates `query --since/--before` compare against, and the `--since` the
+// changelog hands to git) resolves to the local calendar day. Deriving
+// stamps from UTC while comparing against local-midnight boundaries made the
+// same date mean different days: west of UTC after ~13:00 local, a fresh
+// entity was stamped with tomorrow.
+function pad(n) {
+    return String(n).padStart(2, '0');
+}
+/** The local calendar day as YYYY-MM-DD. The single source of "today". */
+export function localDay(d = new Date()) {
+    return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
+}
+/**
+ * Bare YYYY-MM-DD → local midnight, for git's approxidate. A date-only
+ * `--since` is otherwise filled with the *current* time of day ("since right
+ * now"), and any explicit instant must anchor to the same local day boundary
+ * the stamps and query comparisons use. Relative forms (`7.days.ago`) are
+ * already local and pass through untouched.
+ */
+export function normalizeSinceDate(since) {
+    return /^\d{4}-\d{2}-\d{2}$/.test(since) ? `${since}T00:00:00` : since;
+}