@tduyng/pi-timbre 0.0.0-stage → 0.0.2

package/src/memory.ts

@@ -0,0 +1,238 @@
+import { mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { createHash } from 'node:crypto'
+import { Validator } from 'ata-validator'
+import { t } from 'ata-validator/t'
+
+import type { JsonValue } from '@earendil-works/pi-ai'
+const isBoolean = new Validator(t.boolean()).isValidObject
+const isStringArray = new Validator(t.array(t.string())).isValidObject
+const isString = new Validator(t.string()).isValidObject
+
+type JsonObject = { [key: string]: JsonValue }
+
+export type Domain = 'prose'
+
+export type Sample = {
+    at: number
+    prevented: boolean
+    domain: Domain
+    chars: number
+    hits: number
+    ids: string[]
+    cacheRead?: number
+    cacheWrite?: number
+}
+
+export type Settings = {
+    prevent?: boolean
+}
+
+export type Notice = {
+    at: number
+    session: string
+    path: string
+}
+
+export type Memory = {
+    version: 1
+    samples: Sample[]
+    notices?: Notice[]
+    settings?: Settings
+}
+
+const EMPTY: Memory = { version: 1, samples: [], notices: [] }
+const MAX_SAMPLES = 500
+const MAX_NOTICES = 500
+const MAX_MEMORY_BYTES = 2 * 1024 * 1024
+
+export function memoryPath(projectRoot: string): string {
+    const digest = createHash('sha256').update(projectRoot).digest('hex').slice(0, 16)
+    const base = process.env['XDG_STATE_HOME'] || join(homedir(), '.local', 'state')
+    return join(base, 'timbre', `${digest}.json`)
+}
+
+export function load(path: string): Memory {
+    try {
+        if (statSync(path).size > MAX_MEMORY_BYTES) return { ...EMPTY }
+        const raw = readFileSync(path, 'utf-8')
+        return parseMemory(JSON.parse(raw) as JsonValue)
+    } catch {
+        return { ...EMPTY }
+    }
+}
+
+const UnknownRecordSchema = t.object({}, { additionalProperties: true })
+const isUnknownRecordSchema = new Validator(UnknownRecordSchema).isValidObject
+const FiniteNonnegativeSchema = t.number({ minimum: 0 })
+const isFiniteNonnegativeSchema = new Validator(FiniteNonnegativeSchema).isValidObject
+const DomainSchema = t.literal('prose')
+const isDomainSchema = new Validator(DomainSchema).isValidObject
+
+function isRecord(value: JsonValue | undefined): value is JsonObject {
+    return isUnknownRecordSchema(value)
+}
+
+function finiteNonnegative(value: JsonValue | undefined): value is number {
+    return isFiniteNonnegativeSchema(value) && Number.isFinite(value)
+}
+
+function parseSample(value: JsonValue): Sample | undefined {
+    if (!isRecord(value)) return undefined
+    const at = value['at']
+    const prevented = value['prevented']
+    const domain = value['domain'] ?? 'prose'
+    const chars = value['chars']
+    const hits = value['hits']
+    if (!finiteNonnegative(at) || !isBoolean(prevented) || !finiteNonnegative(chars) || !finiteNonnegative(hits)) {
+        return undefined
+    }
+    if (!isDomainSchema(domain)) return undefined
+    const ids = isStringArray(value['ids']) ? value['ids'].slice(0, 100) : []
+    const sample: Sample = { at, prevented, domain, chars, hits, ids }
+    const cacheRead = value['cacheRead']
+    const cacheWrite = value['cacheWrite']
+    if (finiteNonnegative(cacheRead)) sample.cacheRead = cacheRead
+    if (finiteNonnegative(cacheWrite)) sample.cacheWrite = cacheWrite
+    return sample
+}
+
+function parseNotice(value: JsonValue): Notice | undefined {
+    if (!isRecord(value)) return undefined
+    const at = value['at']
+    const session = value['session']
+    const path = value['path']
+    if (!finiteNonnegative(at)) return undefined
+    if (!isString(session) || !isString(path)) return undefined
+    return { at, session, path }
+}
+
+export function parseMemory(parsed: JsonValue | undefined): Memory {
+    if (!isRecord(parsed) || parsed['version'] !== 1) return { ...EMPTY }
+    const rows = Array.isArray(parsed['samples']) ? parsed['samples'].slice(-MAX_SAMPLES) : []
+    const noted = Array.isArray(parsed['notices']) ? parsed['notices'].slice(-MAX_NOTICES) : []
+    return {
+        version: 1,
+        samples: evict(rows.map(parseSample).filter((sample): sample is Sample => sample !== undefined)),
+        notices: noted.map(parseNotice).filter((notice): notice is Notice => notice !== undefined),
+        settings: sanitizeSettings(parsed['settings'])
+    }
+}
+
+function sanitizeSettings(raw: JsonValue | undefined): Settings | undefined {
+    if (!isRecord(raw)) return undefined
+    const settings: Settings = {}
+    const prevent = raw['prevent']
+    if (prevent === true || prevent === false) settings.prevent = prevent
+    return Object.keys(settings).length > 0 ? settings : undefined
+}
+
+export function save(path: string, memory: Memory): void {
+    try {
+        mkdirSync(dirname(path), { recursive: true })
+        const tmp = `${path}.${process.pid}.tmp`
+        writeFileSync(tmp, JSON.stringify(memory), 'utf-8')
+        renameSync(tmp, path)
+    } catch {}
+}
+
+export function merge(a: Memory, b: Memory): Memory {
+    const seen = new Set(a.samples.map(key))
+    const samples = [...a.samples, ...b.samples.filter((s) => !seen.has(key(s)))].toSorted((x, y) => x.at - y.at)
+    const mineNotices = a.notices ?? []
+    const theirsNotices = b.notices ?? []
+    const seenNotices = new Set(mineNotices.map(noticeKey))
+    const notices = [...mineNotices, ...theirsNotices.filter((x) => !seenNotices.has(noticeKey(x)))]
+    return {
+        version: 1,
+        samples: evict(samples),
+        notices: evictNotices(notices),
+        settings: b.settings ?? a.settings
+    }
+}
+
+function key(s: Sample): string {
+    return `${s.at}:${s.prevented}:${s.domain}:${s.chars}:${s.hits}`
+}
+
+export function record(memory: Memory, ids: string[], sample: Omit<Sample, 'ids'>): Memory {
+    return { ...memory, samples: evict([...memory.samples, { ...sample, ids }]) }
+}
+
+function noticeKey(n: Notice): string {
+    return `${n.session}:${n.path}`
+}
+
+export function appendNotice(memory: Memory, notice: Notice): Memory {
+    return { ...memory, notices: evictNotices([...(memory.notices ?? []), notice]) }
+}
+
+export function noticed(memory: Memory, session: string, path: string): boolean {
+    return (memory.notices ?? []).some((n) => n.session === session && n.path === path)
+}
+
+function evictNotices(notices: Notice[]): Notice[] {
+    return notices.length <= MAX_NOTICES ? notices : notices.slice(-MAX_NOTICES)
+}
+
+function evict(samples: Sample[]): Sample[] {
+    if (samples.length <= MAX_SAMPLES) return samples
+    const on = samples.filter((s) => s.prevented)
+    const off = samples.filter((s) => !s.prevented)
+    const [small, large] = on.length <= off.length ? [on, off] : [off, on]
+
+    const smallKeep = Math.min(small.length, Math.floor(MAX_SAMPLES / 2))
+    const largeKeep = MAX_SAMPLES - smallKeep
+    return [...small.slice(-smallKeep), ...large.slice(-largeKeep)].toSorted((a, b) => a.at - b.at)
+}
+
+export function tallyIds(samples: Sample[]): Map<string, number> {
+    const counts = new Map<string, number>()
+    for (const s of samples) for (const id of s.ids) counts.set(id, (counts.get(id) ?? 0) + 1)
+    return counts
+}
+
+export type Effect = {
+    withPrevention: { samples: number; density: number }
+    withoutPrevention: { samples: number; density: number }
+    delta: number | null
+}
+
+export function effect(memory: Memory, domain: Domain = 'prose'): Effect {
+    const rows = memory.samples.filter((s) => s.domain === domain)
+    const on = rows.filter((s) => s.prevented)
+    const off = rows.filter((s) => !s.prevented)
+    const onD = density(on)
+    const offD = density(off)
+    return {
+        withPrevention: { samples: on.length, density: onD },
+        withoutPrevention: { samples: off.length, density: offD },
+        delta:
+            off.length === 0 || on.length === 0
+                ? null
+                : offD === 0
+                  ? onD === 0
+                      ? 0
+                      : -100
+                  : ((offD - onD) / offD) * 100
+    }
+}
+
+function density(xs: Sample[]): number {
+    const chars = xs.reduce((a, s) => a + s.chars, 0)
+    const hits = xs.reduce((a, s) => a + s.hits, 0)
+    return chars === 0 ? 0 : (hits / chars) * 1000
+}
+
+export type CacheSummary = { turns: number; avgCacheRead: number; avgCacheWrite: number }
+
+export function cacheSummary(memory: Memory, prevented: boolean): CacheSummary | null {
+    const turns = memory.samples.filter(
+        (s) => s.domain === 'prose' && s.prevented === prevented && s.cacheRead !== undefined
+    )
+    if (turns.length === 0) return null
+    const reads = turns.reduce((a, s) => a + (s.cacheRead ?? 0), 0)
+    const writes = turns.reduce((a, s) => a + (s.cacheWrite ?? 0), 0)
+    return { turns: turns.length, avgCacheRead: reads / turns.length, avgCacheWrite: writes / turns.length }
+}

package/src/patterns.ts

@@ -0,0 +1,255 @@
+export type Tier = 'forensic' | 1 | 2
+export type Scope = 'prose' | 'url'
+
+export type Pattern = {
+    id: string
+    tier: Tier
+    re: RegExp
+    hint: string
+    scope?: Scope
+}
+
+export const PATTERNS: Pattern[] = [
+    {
+        id: 'tool-leakage',
+        tier: 'forensic',
+        scope: 'url',
+        re: /citeturn\d|contentReference\[oaicite:|oai_citation|attributableIndex|utm_source=(chatgpt\.com|openai|copilot\.com|perplexity)|referrer=grok\.com/i,
+        hint: 'Strip the citation token or tracking parameter.'
+    },
+    {
+        id: 'invisible-unicode',
+        tier: 'forensic',
+        scope: 'url',
+        re: /\u200B|\u200C|\u200D|\u2060|\uFEFF|\u00AD/,
+        hint: 'Delete the zero-width or soft-hyphen character.'
+    },
+    {
+        id: 'placeholder',
+        tier: 'forensic',
+        re: /\[(your name|insert [a-z ]+|company name|todo)\]|\b20\d\d-XX-XX\b/i,
+        hint: 'Fill the placeholder or cut the line.'
+    },
+    {
+        id: 'reasoning-artifact',
+        tier: 'forensic',
+        re: /^\s*(first, i'?ll\b|let me think\b|breaking this down\b)/i,
+        hint: 'Delete the scaffolding, keep the conclusion.'
+    },
+
+    {
+        id: 'em-dash',
+        tier: 1,
+        re: /—|–/,
+        hint: 'Comma, period, colon, or parentheses.'
+    },
+    {
+        id: 'semicolon',
+        tier: 1,
+        re: /(?<!&#\d{1,6}|&#x[0-9a-f]{1,5}|&[a-z][a-z0-9]{1,30});/i,
+        hint: 'Split into two sentences.'
+    },
+    {
+        id: 'curly-quote',
+        tier: 1,
+        re: /[‘’“”…]/,
+        hint: 'Straight quotes, three periods.'
+    },
+    {
+        id: 'emoji',
+        tier: 1,
+        re: /[\u{1F300}-\u{1FAFF}\u{1F900}-\u{1F9FF}]/u,
+        hint: 'Remove the decoration.'
+    },
+    {
+        id: 'bold-label-bullet',
+        tier: 1,
+        re: /^\s*[-*+]\s+\*\*[^*]{1,40}:\*\*/,
+        hint: 'Write it as prose, or drop the bold label.'
+    },
+    {
+        id: 'list-label-period',
+        tier: 1,
+        re: /^\s*[-*+]\s+\*\*[^*]{1,40}\.\*\*\s+\S/,
+        hint: 'Use a colon, not a period, on a list label. Or write it as prose.'
+    },
+
+    {
+        id: 'ai-vocabulary',
+        tier: 1,
+        re: /\b(tapestry|nestled|boasts|bustling|myriad|leverage|leveraging|delve|delving|garner|garnering|holistic|multifaceted|synergy|treasure trove|utilize|utilizing|facilitate|facilitating|elucidate|endeavor|encompass|encompassing|paradigm|catalyze|catalyzing|juxtapose|realm|plethora|galvanize|galvanizing|epitomize|epitomizing|unravel|unraveling|catapult|catapulting|conceptualize|supercharge|supercharging|spearhead|spearheading|commence|commencing|top[- ]notch)\b/i,
+        hint: 'Use the plain word. "utilize" is always "use".'
+    },
+
+    {
+        id: 'negative-parallelism',
+        tier: 1,
+        re: /\bit(?:'?s| is) not (just|merely)\b|\bnot only\b.{0,60}\bbut also\b|\b(?:isn'?t|aren'?t|wasn'?t|weren'?t)\b[^.\n]{2,60},\s*(?:it|that)'s\b/i,
+        hint: 'State the positive claim alone.'
+    },
+    {
+        id: 'throat-clearing',
+        tier: 1,
+        re: /\bhere(?:'?s| is) the thing\b|\bin today'?s\b|\bat its core\b|\bit(?:'?s| is) worth noting\b|\bit(?:'?s| is) important to (note|remember|highlight|mention)\b|\bthe real question is\b|\bwhen it comes to\b|\bat the end of the day\b|\bneedless to say\b|\bit turns out\b|\bthe truth is\b|\blet me be clear\b|\bin a nutshell\b|\brest assured\b|\bit goes without saying\b/i,
+        hint: 'Delete it and state the point.'
+    },
+    {
+        id: 'signposting',
+        tier: 1,
+        re: /\blet'?s (dive|explore|break (this|it) down)|\bdelv(e|ing) into\b|\bwithout further ado\b/i,
+        hint: 'Delete the announcement, keep the content.'
+    },
+    {
+        id: 'mannered-flourish',
+        tier: 1,
+        re: /\bearn(?:s|ed)? (?:its|their) keep\b|\bpull(?:s|ed)? (?:its|their) (?:own )?weight\b|\b(?:does|doing|did) the heavy lifting\b|\bmoves? the needle\b/i,
+        hint: 'Say the literal thing: what it does, or why it matters.'
+    },
+    {
+        id: 'chat-artifact',
+        tier: 1,
+        re: /\bI hope this helps\b|\bwould you like me to\b|\bgreat question\b|\byou'?re absolutely right\b|\bfeel free to\b|\bdon'?t hesitate to\b|\bI love that you asked\b|\bhappy to help\b|\bi'?d be happy to\b|\blet me know if\b|\bcertainly!\b|\bof course!\b|\bthat'?s a great point\b|\byou'?re asking about\b|\bto answer your question\b/i,
+        hint: 'Delete the assistant chatter, answer directly.'
+    },
+
+    {
+        id: 'claudism',
+        tier: 1,
+        re: /\bworth sitting with\b|\bkeep arriving at\b|\bthe question (that kept|that keeps|i keep) coming (up|back to)\b|\bhere'?s where it gets interesting\b|\bdouble-click on\b|\bthroughline\b|\bthrough-line\b|\bthe whole (game|ballgame)\b|\bthat'?s the entire point\b|\bthe only thing that (matters|mattered|happened|changed)\b|\bworth (talking about|drawing|making|examining|considering|exploring)\b|\b(which |that )?brings (me|us) back to\b|\bwe'?ve seen this movie before\b|\bthe thing that (got me|hooked me|got to me)\b|\bdispatches from\b|\bi can'?t stop thinking about\b|\bthat'?s the tell\b|\bthe tell is\b|\bshed light on\b|\bpave(s|d)? the way\b|\bit cannot be overstated\b|\bthis is where\b.{0,40}\bcomes in\b/i,
+        hint: 'Pseudo-reflective framing. State the thing directly.'
+    },
+
+    {
+        id: 'false-agency',
+        tier: 1,
+        re: /\b(?:numbers|results|data|figures) speak for (?:themselves|itself)\b|\btells? a (?:clear )?story\b|\bpaints? a (?:clear |vivid )?picture\b|\bspeaks volumes\b/i,
+        hint: 'State the finding yourself. Data does not narrate.'
+    },
+    {
+        id: 'colon-reveal',
+        tier: 1,
+        re: /\b(?:the )?(?:answer|secret|trick|truth|reality|lesson) (?:is|was|remains)\s*:|\b(?:the )?(?:bottom line|key takeaway|takeaway)\s*:/i,
+        hint: 'State the point. The setup colon manufactures a reveal.'
+    },
+
+    {
+        id: 'future-narrative',
+        tier: 1,
+        re: /\bthe (?:next|coming|upcoming)\s+(?:era|decade|chapter|frontier|market cycle|paradigm|iteration|wave|phase|epoch)\b|\bis (?:set|destined|poised)\s+to\s+(?:be|become|define|reshape|redefine|transform)\b/i,
+        hint: 'Pick the falsifiable version, or cut it. The template shape is not a prediction.'
+    },
+    {
+        id: 'confidence-calibration',
+        tier: 1,
+        re: /\b(?:interestingly|surprisingly|notably|fascinatingly|remarkably|unsurprisingly|tellingly)\b/i,
+        hint: 'Let the fact speak for itself. Cut the calibration word.'
+    },
+    {
+        id: 'listicle-trench',
+        tier: 1,
+        re: /\bthe (?:first|second|third) (?:wall|step|pillar|phase|wave|stage|reason|lesson|takeaway) is\b/i,
+        hint: 'A hidden numbered list. Make it a list, or weave the points without numbering.'
+    },
+
+    {
+        id: 'fronted-participle',
+        tier: 2,
+        re: /(?:^|(?<=[.!?])\s+)(?:(?!(?:According|Regarding|Concerning|Depending|Seeing|Nothing|Something|Anything|Everything|Morning|Evening|Building|String|During|Ceiling|Meeting|Spring|Ring|Wing|King)\b)[A-Z][a-z]*ing\s+(?:the|a|an|its|their|his|her|our|your|this|that|these|those|on|in|into|with|for|from|at|by|to)|Having\s+[a-z]+(?:ed|ing|en)|By\s+[a-z]+ing)\b[^,.;:!?\n]{0,60}?,\s+(?:the|a|an|this|that|these|those|its|their|our|your|his|her|we|you|they|it|he|she|i)\b/,
+        hint: 'Name the actor first. "The team ran the suite" beats "Running the suite, the team".'
+    },
+    {
+        id: 'participial-padding',
+        tier: 2,
+        re: /,\s+(?:highlighting|underscoring|showcasing|fostering|reflecting|demonstrating|signaling|signalling|ensuring|emphasizing|emphasising|paving the way)\b/i,
+        hint: 'The -ing tail adds significance instead of information. Cut it, or make it a sentence.'
+    }
+]
+
+export const TIER_2_WORDS = [
+    'robust',
+    'comprehensive',
+    'innovative',
+    'streamline',
+    'empower',
+    'enhance',
+    'optimize',
+    'scalable',
+    'profound',
+    'cultivate',
+    'bolster',
+    'cornerstone',
+    'groundbreaking',
+    'transformative',
+    'unprecedented',
+    'compelling',
+    'versatile',
+    'vibrant',
+    'hone',
+    'tailor',
+    'revolutionize',
+    'amplify',
+    'discern',
+    'cutting-edge',
+    'pivotal',
+    'seamless',
+    'harness',
+    'unlock',
+    'unleash',
+    'elevate',
+    'foster',
+    'meticulous',
+    'invaluable',
+    'unwavering',
+    'bespoke',
+    'interplay',
+    'intricate',
+    'resonate',
+    'illuminate',
+    'captivate',
+    'nuanced',
+    'paramount',
+    'burgeoning',
+    'ubiquitous',
+    'aforementioned',
+    'pertaining to',
+    'noteworthy',
+    'delineate',
+    'underpin',
+    'unveil',
+    'double-edged sword',
+    'sheds light',
+    'strikes a balance',
+    'substrate',
+    'flywheel',
+    'north star',
+    'nexus',
+    'endgame',
+    'gold-plating',
+    'vantage point',
+    'locus',
+    'quietly',
+    'genuinely',
+    'inherently'
+] as const
+
+export const TIER_3_PHRASES = [
+    'the integration of',
+    'decentralized compute',
+    'community-driven',
+    'long-term sustainability',
+    'seamless integration',
+    'cutting-edge solution',
+    'robust solution',
+    'future-proof',
+    'best-in-class',
+    'world-class',
+    'turn-key',
+    'scalable solution',
+    'streamlined workflow',
+    'powerful tool',
+    'blazing fast',
+    'state-of-the-art',
+    'next-generation'
+] as const
+
+export const byId = new Map(PATTERNS.map((p) => [p.id, p]))

package/src/register.ts

@@ -0,0 +1,35 @@
+export type Register = 'reference' | 'changelog' | 'narrative' | 'chat' | 'unknown'
+
+export type Profile = {
+    register: Register
+    terseIsCorrect: boolean
+    voiceAllowed: boolean
+}
+
+const PROFILES = {
+    reference: { register: 'reference', terseIsCorrect: true, voiceAllowed: false },
+    changelog: { register: 'changelog', terseIsCorrect: true, voiceAllowed: false },
+    narrative: { register: 'narrative', terseIsCorrect: false, voiceAllowed: true },
+    chat: { register: 'chat', terseIsCorrect: true, voiceAllowed: true },
+    unknown: { register: 'unknown', terseIsCorrect: false, voiceAllowed: false }
+} satisfies Record<Register, Profile>
+
+const SEG = String.raw`(?:^|/)`
+
+const RULES: Array<[RegExp, Register]> = [
+    [new RegExp(`${SEG}(blog|posts?|essays?|articles?|drafts?)/`, 'i'), 'narrative'],
+    [new RegExp(`${SEG}(CHANGELOG|HISTORY|RELEASE[-_]?NOTES)`, 'i'), 'changelog'],
+    [/COMMIT_EDITMSG|\.git\//, 'changelog'],
+    [new RegExp(`${SEG}(adr|rfc|spec|specs|reference|api)/`, 'i'), 'reference'],
+    [/(README|CONTRIBUTING|AGENTS|CLAUDE)\.mdx?$/i, 'reference'],
+    [new RegExp(`${SEG}docs?/`, 'i'), 'reference']
+]
+
+export function classify(path: string): Profile {
+    for (const [re, register] of RULES) {
+        if (re.test(path)) return PROFILES[register]
+    }
+    return PROFILES.unknown
+}
+
+export const chatProfile = PROFILES.chat