@sema-agent/core/dist/core/memory-engine/header-hints.d.ts

Stateless, task-oriented AI agent core

/**
 * design/180 裁决 C — the v2 header hints, read-only, over `frontmatter.extra`.
 *
 * The v2 header fields (pinned / triggers / last-confirmed / applies-when) are DELIBERATELY not
 * typed structure positions: the parser's closed grammar keeps unknown lines VERBATIM in `extra`,
 * `extra` participates in the entry rev, and the sync wire carries it — so a file with these lines
 * computes the SAME rev on every client vintage (old and new), and no backend/sync twin owes an
 * upgrade. Promoting them to typed fields would make the same bytes hash to two different revs
 * across a mixed fleet (the provenance note in frontmatter.ts names that exact incident shape).
 *
 * This accessor is the ONLY consumer-side reading: pure, lenient, and closed over bad values —
 * a malformed line reads as FIELD ABSENT, never an error and never a partial adoption. Nothing in
 * the engine writes these lines; the model does (the preference-discipline paragraph teaches it),
 * because an engine-written confirmation would self-declare the usage evidence it is supposed to record.
 */
/** The parsed v2 hints. Every field is absent unless a well-formed line was found. */
export interface V2HeaderHints {
    /** `pinned: true` — only the exact literal counts (anything else = absent). */
    pinned?: boolean;
    /** `triggers: a, b, c` — comma-split, trimmed, empties dropped; an empty result = absent. */
    triggers?: string[];
    /** `last-confirmed: YYYY-MM-DD…` — kept as the raw string when it starts with an ISO-date shape;
     *  anything else = absent (bad values must not masquerade as confirmations). */
    lastConfirmedAt?: string;
    /** `applies-when: <free text>` — non-empty free text, trimmed. */
    appliesWhen?: string;
}
/**
 * design/336 §4.1 — the MECHANICAL instruction-form predicate (deliberately zero semantic judgment:
 * no model, no content heuristics — SOTA R4's LLM-judge ban). An entry is instruction-form ⇔
 *  - `metadata.type === "feedback"` (the declared behavior-correction type), OR
 *  - its v2 header hints declare an injection/trigger privilege: `pinned` / `triggers` /
 *    `applies-when` (the three hints whose whole purpose is automatic or conditional injection;
 *    `last-confirmed` is bookkeeping and does not count).
 * Escape analysis: an entry that declares none of these rides the ordinary-entry row — where the
 * origin-marker floor governs — so NOT declaring buys no privilege; declaring buys injection
 * privilege AND walks through the exposure hard gate with it. ONE exported predicate on purpose:
 * the write side (harvest hard gate) and any read-side consumer must judge through the same
 * function, never through re-implementations that can drift.
 *
 * NAME COLLISION, not concept parity (test B12): `pinned` here is a
 * WRITE-SIDE safety-privilege declaration (instruction-form ⇒ exposure hard gate / quarantine),
 * while Claude Code's `pinned` is a RECALL-side display priority (up to 4 entries surfaced in a
 * "# Pinned memories" block). Same word, different machines — do not read one as the other.
 */
export declare function isInstructionEntry(fm: {
    type?: string;
    extra?: readonly string[];
}): boolean;
/** Read the v2 header hints out of an entry's preserved-verbatim `extra` lines. First well-formed
 *  occurrence of each key wins (duplicate lines are model bookkeeping noise, not a merge input). */
export declare function readV2HeaderHints(extra: readonly string[] | undefined): V2HeaderHints;