Precision, triggers and the miss share count only rows after the gate-1
fix merge (d3d5e6c, 2026-11-12T19:53:59Z); their actions wait for 20
post-fix asks, a one-off NEW line marks the sample and the reminder
keeps prompting until then. The 3rd-pick signal is gone. The reader
holds one parsed transcript at a time. labels.tsv rows and state.json
are validated on read. Exact key sets of log records pinned.
225 lines
8.9 KiB
TypeScript
225 lines
8.9 KiB
TypeScript
// lib/memory-feedback/labels.ts: labels.tsv rows (append-only), the
|
|
// labeller's draft and state.json (phase 4d). IDs, enums and repo tags
|
|
// only, never text (LRN-124).
|
|
import { createHash } from 'node:crypto'
|
|
import * as fs from 'node:fs'
|
|
import * as path from 'node:path'
|
|
|
|
export type Channel = 'prompt' | 'tool'
|
|
export type Label = 'relevant' | 'irrelevant' | 'test' | 'missed' |
|
|
'checked' | 'ask' | 'lost'
|
|
const DRAFT_LABELS = ['relevant', 'irrelevant', 'test', 'missed', 'checked']
|
|
const ENTRY_LABELS = ['relevant', 'irrelevant']
|
|
const CAUSES = ['no-overlap', 'overlap']
|
|
const ID_RE = /^(BDR|LRN|BLK)-\d{3,}$/
|
|
const ROW_LABELS = [...DRAFT_LABELS, 'ask', 'lost']
|
|
const BARE_LABELS = ['ask', 'lost', 'test', 'checked'] // carry no entry id
|
|
|
|
/** One worksheet item: a log record and what the join found. */
|
|
export type Item = {
|
|
n: number; root: string; session: string; at: number; channel: Channel
|
|
trigger: string; outcome: string; cands?: number; ms?: number
|
|
ids: string[]; cited: string[]; lost: boolean
|
|
}
|
|
export type Row = {
|
|
at: number; root: string; session: string; channel: Channel
|
|
trigger: string; outcome: string; cands?: number; ms?: number
|
|
pick?: number; id: string; label: Label; cause: string
|
|
}
|
|
export type Draft = { item: number; id: string; label: Label; cause: string }
|
|
/** promptAt/toolAt/postFixAt: when each gate verdict or floor was first
|
|
* reached. */
|
|
export type State = {
|
|
lastRun: number; promptAt?: number; toolAt?: number; closed: boolean
|
|
postFixAt?: number // the post-fix prompt floor, first crossed (optional)
|
|
}
|
|
|
|
const COLS = ['at', 'root', 'session', 'channel', 'trigger', 'outcome',
|
|
'cands', 'ms', 'pick', 'id', 'label', 'cause']
|
|
const HEADER = COLS.join('\t') + '\n'
|
|
|
|
/** A repo tag: basename + 6 hex of the path (same names stay apart). */
|
|
export const tagOf = (root: string) => `${path.basename(root)}#` +
|
|
createHash('sha1').update(root).digest('hex').slice(0, 6)
|
|
|
|
/** One record's identity: session ids are unique across repos. */
|
|
export const keyOf = (r: { session: string; at: number; channel: string }) =>
|
|
`${r.session}|${r.at}|${r.channel}`
|
|
|
|
const num = (v: number | undefined) => v === undefined ? '' : String(v)
|
|
const opt = (s: string | undefined) =>
|
|
s === undefined || s === '' ? undefined : Number(s)
|
|
|
|
export function toLine(r: Row): string {
|
|
return [r.at, r.root, r.session, r.channel, r.trigger, r.outcome,
|
|
num(r.cands), num(r.ms), num(r.pick), r.id, r.label, r.cause]
|
|
.join('\t')
|
|
}
|
|
|
|
/** Whether the fields hold a known label, its id shape, a channel and
|
|
* an integer `at`. */
|
|
function sound(f: string[]): boolean {
|
|
const label = f[10] ?? ''
|
|
const id = f[9] ?? ''
|
|
const idOk = BARE_LABELS.includes(label) ? id === '' : ID_RE.test(id)
|
|
return ROW_LABELS.includes(label) && idOk &&
|
|
(f[3] === 'prompt' || f[3] === 'tool') && /^\d+$/.test(f[0] ?? '')
|
|
}
|
|
|
|
/** A labels.tsv line as a row; the header or a damaged line: undefined. */
|
|
export function fromLine(line: string): Row | undefined {
|
|
const f = line.split('\t')
|
|
if (f.length !== COLS.length || !sound(f)) return undefined
|
|
return {
|
|
at: Number(f[0]), root: f[1] ?? '', session: f[2] ?? '',
|
|
channel: f[3] as Channel, trigger: f[4] ?? '', outcome: f[5] ?? '',
|
|
cands: opt(f[6]), ms: opt(f[7]), pick: opt(f[8]), id: f[9] ?? '',
|
|
label: f[10] as Label, cause: f[11] ?? '',
|
|
}
|
|
}
|
|
|
|
const mkdir = (file: string) => {
|
|
const dir = path.dirname(file)
|
|
fs.mkdirSync(dir, { recursive: true, mode: 0o700 })
|
|
fs.chmodSync(dir, 0o700) // an existing dir may have been looser
|
|
}
|
|
|
|
/** Writes through a 0600 temp file and a rename; the dir is made 0700. */
|
|
export function writeSafe(file: string, text: string): void {
|
|
mkdir(file)
|
|
const tmp = `${file}.${process.pid}.tmp`
|
|
fs.writeFileSync(tmp, text, { mode: 0o600 })
|
|
fs.renameSync(tmp, file)
|
|
}
|
|
|
|
/** Every row; a damaged line fails loudly, it is never dropped. */
|
|
export function readRows(file: string): Row[] {
|
|
if (!fs.existsSync(file)) return []
|
|
const lines = fs.readFileSync(file, 'utf8').split('\n')
|
|
return lines.flatMap((line, i) => {
|
|
if (line === '' || line === HEADER.trimEnd()) return []
|
|
const r = fromLine(line)
|
|
if (r !== undefined) return [r]
|
|
throw new Error(`labels.tsv line ${i + 1} unreadable: fix it by hand ` +
|
|
'(labels.tsv.bak holds the state before the last append)')
|
|
})
|
|
}
|
|
|
|
/** Appends rows; the previous file is copied to labels.tsv.bak first (one
|
|
* state: the one before the last append). */
|
|
export function appendRows(file: string, rows: Row[]): void {
|
|
mkdir(file)
|
|
if (fs.existsSync(file)) fs.copyFileSync(file, `${file}.bak`)
|
|
else fs.writeFileSync(file, HEADER, { mode: 0o600 })
|
|
fs.appendFileSync(file, rows.map(r => toLine(r) + '\n').join(''))
|
|
}
|
|
|
|
/** state.json; absent: a first run; unparsable: a loud error. */
|
|
export function readState(file: string): State {
|
|
if (!fs.existsSync(file)) return { lastRun: 0, closed: false }
|
|
try {
|
|
const s = JSON.parse(fs.readFileSync(file, 'utf8'))
|
|
if (typeof s !== 'object' || s === null || Array.isArray(s)) {
|
|
throw new Error('state.json is not an object')
|
|
}
|
|
const at = (v: unknown) => typeof v === 'number' ? v : undefined
|
|
const [promptAt, toolAt, postFixAt] =
|
|
[at(s.promptAt), at(s.toolAt), at(s.postFixAt)]
|
|
// closed is derived: a stored flag without all three marks reads open
|
|
const closed = promptAt !== undefined && toolAt !== undefined &&
|
|
postFixAt !== undefined
|
|
return { lastRun: Number(s.lastRun) || 0, promptAt, toolAt, postFixAt,
|
|
closed }
|
|
} catch {
|
|
throw new Error(`state.json unreadable (${file}): fix or delete it`)
|
|
}
|
|
}
|
|
|
|
export const writeState = (file: string, s: State) =>
|
|
writeSafe(file, JSON.stringify(s) + '\n')
|
|
|
|
/** One draft line `item<TAB>id<TAB>label[<TAB>cause]`, or why not. */
|
|
function parseLine(line: string): Draft | string {
|
|
const f = line.split('\t')
|
|
if (f.length < 3 || f.length > 4) return `bad field count: ${line}`
|
|
const item = Number(f[0])
|
|
const label = f[2] ?? ''
|
|
if (!Number.isInteger(item)) return `bad item: ${f[0]}`
|
|
if (!DRAFT_LABELS.includes(label)) return `bad label: '${label}'`
|
|
return { item, id: f[1] ?? '', label: label as Label, cause: f[3] ?? '' }
|
|
}
|
|
|
|
/** Why `d` does not fit item `it`; '' when it fits. */
|
|
function fitError(d: Draft, it: Item | undefined): string {
|
|
if (it === undefined || it.lost) return `unknown or lost item ${d.item}`
|
|
const plain = d.cause === ''
|
|
if (d.id === '-') {
|
|
return plain && (d.label === 'checked' || d.label === 'test')
|
|
? '' : `item ${d.item}: only checked or test take id -`
|
|
}
|
|
if (ENTRY_LABELS.includes(d.label)) {
|
|
if (!plain) return `item ${d.item}: ${d.label} takes no cause`
|
|
return it.ids.includes(d.id)
|
|
? '' : `item ${d.item}: ${d.id} was not injected there`
|
|
}
|
|
const ok = d.label === 'missed' && it.channel === 'prompt' &&
|
|
ID_RE.test(d.id) && !it.ids.includes(d.id) && CAUSES.includes(d.cause)
|
|
return ok ? '' : `item ${d.item}: bad ${d.label} row ${d.id} ${d.cause}`
|
|
}
|
|
|
|
/** Every injected entry of every joined item labelled exactly once. */
|
|
function completeError(drafts: Draft[], items: Item[]): string {
|
|
const whole = new Set(drafts.filter(d => d.id === '-' &&
|
|
d.label === 'test').map(d => d.item))
|
|
const got = drafts.filter(d => ENTRY_LABELS.includes(d.label))
|
|
.map(d => `${d.item}:${d.id}`)
|
|
if (new Set(got).size !== got.length) return 'an entry is labelled twice'
|
|
for (const it of items) {
|
|
if (it.lost || whole.has(it.n)) continue
|
|
const miss = it.ids.find(id => !got.includes(`${it.n}:${id}`))
|
|
if (miss !== undefined) return `item ${it.n}: ${miss} unlabelled`
|
|
}
|
|
return ''
|
|
}
|
|
|
|
/** The validated draft, or the first problem found. */
|
|
export function parseDraft(text: string, items: Item[]): Draft[] | string {
|
|
const byN = new Map(items.map(i => [i.n, i]))
|
|
const drafts: Draft[] = []
|
|
for (const line of text.split('\n')) {
|
|
if (line.trim() === '' || line.startsWith('#')) continue
|
|
const d = parseLine(line)
|
|
if (typeof d === 'string') return d
|
|
const err = fitError(d, byN.get(d.item))
|
|
if (err !== '') return err
|
|
drafts.push(d)
|
|
}
|
|
const err = completeError(drafts, items)
|
|
return err === '' ? drafts : err
|
|
}
|
|
|
|
const base = (it: Item) => ({
|
|
at: it.at, root: it.root, session: it.session, channel: it.channel,
|
|
trigger: it.trigger, outcome: it.outcome, cands: it.cands, ms: it.ms,
|
|
})
|
|
|
|
/** The labels.tsv rows of one item: its ask row, then its draft rows. */
|
|
export function rowsOf(it: Item, drafts: Draft[]): Row[] {
|
|
const head: Row = { ...base(it), id: '',
|
|
label: it.lost ? 'lost' : 'ask', cause: '' }
|
|
const mine = drafts.filter(d => d.item === it.n).map((d): Row => ({
|
|
...base(it), id: d.id === '-' ? '' : d.id,
|
|
pick: it.ids.includes(d.id) ? it.ids.indexOf(d.id) + 1 : undefined,
|
|
label: d.label, cause: d.cause,
|
|
}))
|
|
return [head, ...mine]
|
|
}
|
|
|
|
/** A draft to fill in: one `<item> <id> ` line per injected id. */
|
|
export function skeleton(items: Item[]): string {
|
|
const lines = items.filter(i => !i.lost)
|
|
.flatMap(i => i.ids.map(id => `${i.n}\t${id}\t`))
|
|
return ['# fill the 3rd column: relevant or irrelevant', ...lines]
|
|
.join('\n') + '\n'
|
|
}
|