@tenphi/akno-core 0.1.0

package/dist/maintenance/observe.js

@@ -0,0 +1,265 @@
+import { z } from 'zod';
+import { parseJsonLoose } from "../models/client.js";
+import { contentWords } from "../kb/words.js";
+/**
+ * **Observe: combine repeated facts into stable patterns and habits. Never restate the
+ * facts.**
+ *
+ * This tier is an inference engine writing prose into a knowledge base, and in a prose
+ * knowledge base a bad write is recalled later **as truth**. So the guardrails are
+ * enforced here in code, not asked for in the prompt:
+ *
+ * - **Evidence or nothing.** At least `min_evidence` distinct source pages, and every slug
+ *   checked against the pages actually shown to the model. A model citing a page it was
+ *   never given is the failure mode this exists for.
+ * - **No hedged language, ever.** "might", "seems", "possibly" — a hedge written as prose
+ *   reads as an assertion three months later, when nobody remembers it was a guess.
+ * - **Never restate the facts.** A line that repeats a source line adds nothing and costs a
+ *   recall slot; the point of the tier is the pattern *across* facts.
+ * - **Nothing about a person's health, relationships, finances, beliefs or character.** The
+ *   canonical example of what this tier must not do. The prompt says it too, and a real run wrote
+ *   "X lives with a wife" anyway — which is why it is a guard and not only an instruction.
+ * - **Nothing about the records themselves.** "Each location is described by a street address"
+ *   is an observation about a knowledge base, not about a life, and it is what a model reaches
+ *   for when the facts have nothing else in common.
+ * - **Missions are additive.** The mission string appends emphasis to this fixed prompt and
+ *   never replaces it, because every rule above lives in the fixed part.
+ *
+ * The caller enforces the two guards that need the knowledge base rather than the text:
+ * `full` pages only, and no observation as evidence for another observation.
+ */
+const SYSTEM = `You look for stable patterns across facts already recorded in a personal knowledge base.
+
+You are given facts grouped by subject, each tagged with the page it came from. Reply with JSON only:
+
+{
+  "observations": [
+    { "pattern": "one sentence stating a stable pattern, habit, or tendency",
+      "evidence": ["page/slug", "another/slug"],
+      "confidence": 0.0 }
+  ]
+}
+
+What counts as a pattern:
+- A habit visible across several separate records: a recurring choice, a repeated interval, a consistent preference.
+- A tendency the facts agree on: how something is usually done, what is usually chosen, what keeps happening.
+
+Hard rules:
+- Every observation needs at least two DIFFERENT pages in "evidence", quoting their slugs exactly as given.
+- Never restate a fact. If your sentence is one of the facts reworded, drop it.
+- Never hedge. No "might", "seems", "possibly", "appears to", "probably". If you are not sure, leave it out.
+- Never infer about someone's health, finances, beliefs, relationships or character. Patterns about
+  practices and preferences only.
+- State the pattern, not the reasoning, and never mention "the facts" or "the pages".
+- Fewer, better. An empty list is the correct answer for facts that share only a subject, and is much
+  better than a vague pattern nobody can act on.
+- You may be shown patterns already recorded for this subject. Never repeat one, and never reword one.
+  Report only what those lines do not already say. If they cover it, return an empty list — that is the
+  expected answer on most nights, because the facts rarely change between one night and the next.`;
+/**
+ * Shape only. Every rule this tier actually depends on — two distinct pages of evidence,
+ * slugs that exist, no hedging, nothing about health or finances — is enforced after the
+ * call, because those are the guards that exist precisely because a prompt could not be
+ * trusted to carry them.
+ */
+export const OBSERVE_SCHEMA = z.object({
+    observations: z.array(z.object({
+        pattern: z.string(),
+        evidence: z.array(z.string()),
+        confidence: z.number(),
+    })),
+});
+/**
+ * The forbidden ground, as a guard rather than an instruction. A real run produced "X lives
+ * with a wife" from two people's pages with the prompt rule in place: an inference about a
+ * relationship, written as prose, recalled later as truth.
+ *
+ * Deliberately narrow. It cannot catch every sensitive inference, and its job is not to — it is
+ * to make the *named categories* impossible to write, so a miss is a gap and never a
+ * licence.
+ */
+const SENSITIVE = /\b(wife|husband|spouse|partner|married|divorced|dating|girlfriend|boyfriend|sibling\w*|brother\w*|sister\w*|son|daughter|children|kids|parents?|family|pregnan\w*|ill|illness|disease|diagnos\w*|depress\w*|anxiet\w*|therapy|medication|salary|debt|broke|wealthy|poor|religio\w*|believes?|faith|prays?|votes?|political|lazy|careless|impulsive|honest|dishonest)\b/i;
+/**
+ * A "pattern" about the shape of the records rather than about anything that happened. What a
+ * model reaches for when the facts under one heading have nothing else in common.
+ */
+const ABOUT_THE_RECORDS = /\b(each (entry|page|record|item|location|line)|every (entry|page|record|item)|is (described|recorded|listed|documented|stored)|these (pages|records|entries|notes)|the (pages|records|entries|dataset|data))\b/i;
+/**
+ * "The records consistently say X" — a single fact with a preamble bolted on.
+ *
+ * Real runs produced "Employment documents consistently record the employee's date of birth as 3
+ * March 1911" and "Employment records consistently identify Vulpine Mutual B.V. as the employer".
+ * Neither is a pattern across facts; each is one fact, restated, with the agreement of the sources
+ * offered as if it were the insight. The first also copies a personal identifier onto a derived page
+ * that nobody asked for it to be on.
+ *
+ * `ABOUT_THE_RECORDS` misses these because the sentence is grammatically about the subject — it is
+ * the *documents* that do the identifying — so the shape has to be matched directly.
+ */
+const RECORDS_SAY = /\b(records?|documents?|entries|files?|statements?|pages?)\b[^.]{0,40}\b(consistently|always|all|repeatedly)?\s*\b(record|records|identify|identifies|show|shows|list|lists|state|states|confirm|confirms|indicate|indicates)\b/i;
+/**
+ * A template rather than a claim. A real run produced "Italian cities are often located at Via
+ * [number] [street name] [zip code]" — a description of how an address is written, dressed as a
+ * fact about cities.
+ */
+const TEMPLATE = /\[[a-z ]{3,20}\]/i;
+/** A hedge in prose is an assertion by the time anyone reads it back. */
+const HEDGES = /\b(might|may|maybe|seems?|appears?|possibly|probably|perhaps|likely|unlikely|could be|suggests?|apparently|tends? to suggest)\b/i;
+export async function runObserveMission(input) {
+    const empty = { observations: [], error: null, rejected: [] };
+    if (!input.model.available) {
+        return { ...empty, error: input.model.unavailableReason ?? 'the model is unavailable' };
+    }
+    const allowed = new Set(input.facts.map((fact) => fact.slug));
+    // Below the floor there is nothing to observe *across*, so the call is skipped rather than
+    // made and then rejected.
+    if (allowed.size < input.minEvidence)
+        return empty;
+    const system = input.mission ? `${SYSTEM}\n\nAdditional emphasis: ${input.mission}` : SYSTEM;
+    const listed = input.facts.map((fact) => `- [${fact.slug}] ${fact.claim}`).join('\n');
+    const known = (input.existing ?? []).slice(0, 20);
+    const alreadyRecorded = known.length > 0
+        ? `\n\nAlready recorded for this subject — do not repeat or reword:\n${known.map((line) => `- ${line}`).join('\n')}`
+        : '';
+    const result = await input.model.chat([
+        { role: 'system', content: system },
+        { role: 'user', content: `Subject: ${input.subject}\n\nFacts:\n${listed}${alreadyRecorded}` },
+    ], { schema: OBSERVE_SCHEMA, maxTokens: 700 });
+    if (!result.ok || !result.value)
+        return { ...empty, error: result.error ?? 'the observe mission failed' };
+    const parsed = parseJsonLoose(result.value);
+    if (!parsed || !Array.isArray(parsed.observations)) {
+        input.model.reportInvalidResponse();
+        return { ...empty, error: 'the observe mission did not return usable JSON' };
+    }
+    const observations = [];
+    const rejected = [];
+    for (const entry of parsed.observations.slice(0, 8)) {
+        if (typeof entry !== 'object' || entry === null)
+            continue;
+        const record = entry;
+        const pattern = typeof record.pattern === 'string' ? record.pattern.trim().replace(/\s+/g, ' ') : '';
+        if (pattern.length < 12 || pattern.length > 400)
+            continue;
+        if (HEDGES.test(pattern)) {
+            rejected.push({ pattern, reason: 'hedged language' });
+            continue;
+        }
+        if (SENSITIVE.test(pattern)) {
+            rejected.push({ pattern, reason: "inferring about a person's private life is out of bounds" });
+            continue;
+        }
+        if (ABOUT_THE_RECORDS.test(pattern)) {
+            rejected.push({ pattern, reason: 'describes the records rather than what they record' });
+            continue;
+        }
+        if (RECORDS_SAY.test(pattern)) {
+            rejected.push({ pattern, reason: 'one fact restated as "the records consistently say it"' });
+            continue;
+        }
+        if (TEMPLATE.test(pattern)) {
+            rejected.push({ pattern, reason: 'a template with placeholders, not a claim' });
+            continue;
+        }
+        // The model was asked not to repeat itself; this is what happens when it does anyway. Only
+        // catches near-identical wording — real rewrites share too few words for any threshold that
+        // would not also merge genuinely different observations, which is why the prompt does the work
+        // and this only backstops it.
+        if (known.some((line) => nearlyTheSame(line, pattern))) {
+            rejected.push({ pattern, reason: 'already recorded for this subject' });
+            continue;
+        }
+        // The same thing said on somebody else's page. Grouping is by folder and subject, so two
+        // groups can reach one conclusion from overlapping facts and each write it to its own page —
+        // where neither looks like a duplicate, because neither page contains the other.
+        if ((input.otherObservations ?? []).some((line) => nearlyTheSame(line, pattern))) {
+            rejected.push({ pattern, reason: 'already recorded on another observation page' });
+            continue;
+        }
+        // Only slugs the model was actually shown. Anything else is invention, and an invented
+        // citation is worse than no observation because it looks checkable.
+        const evidence = [
+            ...new Set((Array.isArray(record.evidence) ? record.evidence : [])
+                .filter((slug) => typeof slug === 'string')
+                .map((slug) => slug.trim())
+                .filter((slug) => allowed.has(slug))),
+        ];
+        if (evidence.length < input.minEvidence) {
+            rejected.push({
+                pattern,
+                reason: `cited ${evidence.length} usable source page(s), needs ${input.minEvidence}`,
+            });
+            continue;
+        }
+        if (restatesAFact(pattern, input.facts.map((fact) => fact.claim).concat(input.knownFacts ?? []))) {
+            rejected.push({ pattern, reason: 'restates a fact rather than observing across them' });
+            continue;
+        }
+        const confidence = typeof record.confidence === 'number' ? clamp(record.confidence) : 0.6;
+        observations.push({ pattern, evidence, confidence });
+    }
+    // One per subject per run, the best the model was willing to stand behind.
+    //
+    // Not a token saving: given a subject with nothing much in common, a model produces three
+    // variations on the same weak idea — a real run wrote three separate "Italian cities are
+    // often located…" lines for one folder. Keeping the strongest makes a thin subject cost one
+    // line instead of three, and the advice for this tier is fewer and better.
+    observations.sort((a, b) => b.confidence - a.confidence);
+    return { observations: observations.slice(0, 1), error: null, rejected };
+}
+/**
+ * **Never restate the facts.** Judged by word overlap against each source claim rather
+ * than by asking the model, because "did you just reword one of these" is exactly the
+ * question a model that rewrote one will answer wrongly.
+ */
+function restatesAFact(pattern, claims) {
+    const patternWords = contentWords(pattern);
+    if (patternWords.size === 0)
+        return true;
+    for (const claim of claims) {
+        const factWords = contentWords(claim);
+        if (factWords.size === 0)
+            continue;
+        let shared = 0;
+        for (const word of patternWords)
+            if (factWords.has(word))
+                shared++;
+        // Four fifths of one claim's content words, in a sentence that is meant to say something
+        // no single claim does.
+        if (shared / patternWords.size >= 0.8)
+            return true;
+    }
+    return false;
+}
+function clamp(value) {
+    if (!Number.isFinite(value))
+        return 0.6;
+    return Math.min(1, Math.max(0, value));
+}
+/**
+ * Two patterns that differ only in wording.
+ *
+ * Content words only, compared as a set — "Total spending declined in each successive period" and
+ * "…in each recorded period" differ by one word out of nine and are plainly the same observation.
+ * The bar is high on purpose: on a page scoped to one subject, every line is about that subject, so
+ * a loose threshold would merge two real patterns about it. Anything a genuine rewrite gets past is
+ * the prompt's job, not this one's.
+ */
+function nearlyTheSame(a, b) {
+    const words = (text) => new Set(text
+        .toLowerCase()
+        .replace(/\[\[[^\]]*\]\]/g, ' ')
+        .replace(/[^a-z0-9\s]/g, ' ')
+        .split(/\s+/)
+        .filter((word) => word.length > 3));
+    const left = words(a);
+    const right = words(b);
+    if (left.size === 0 || right.size === 0)
+        return false;
+    let shared = 0;
+    for (const word of right)
+        if (left.has(word))
+            shared += 1;
+    return shared / new Set([...left, ...right]).size >= 0.75;
+}
+//# sourceMappingURL=observe.js.map

package/dist/maintenance/observe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observe.js","sourceRoot":"","sources":["../../src/maintenance/observe.ts"],"names":[],"mappings":"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"}

package/dist/maintenance/path-policy.d.ts

@@ -0,0 +1,83 @@
+import { type DreamManagement, type PageRole, type RememberManagement } from '@tenphi/akno-protocol';
+import type { AknoConfig, MaintenanceLimits, MaintenancePolicy, MaintenanceProfile, MaintenanceTransform } from '../config/schema.ts';
+import type { AknoContext } from '../context.ts';
+import type { MaintenanceMode } from './plans.ts';
+declare const PAGE_MAINTENANCE_TRANSFORMS: readonly ["hygiene", "managed_item", "synthesis", "split", "extract", "merge", "contradiction", "broken_link", "rule_drift"];
+export type PageMaintenanceTransform = (typeof PAGE_MAINTENANCE_TRANSFORMS)[number];
+export type MaintenancePathState = 'indexed_page' | 'not_indexed' | 'non_page' | 'ignored';
+type MaintenancePolicySource = 'frontmatter' | 'folder_rule' | 'provenance' | 'default';
+export type MaintenancePathOutcome = 'ineligible' | 'off' | 'audit_only' | 'awaiting_human' | 'curator_then_apply' | 'apply_blocked';
+export interface MaintenancePathReason {
+    layer: 'path' | 'page' | 'configuration' | 'policy' | 'budget' | 'model';
+    code: string;
+    message: string;
+}
+export interface MaintenancePathTransformPolicy {
+    kind: PageMaintenanceTransform;
+    configuredPolicy: MaintenancePolicy;
+    effectivePolicy: MaintenancePolicy;
+    outcome: MaintenancePathOutcome;
+    canInspect: boolean;
+    decision: 'none' | 'human' | 'curator';
+    automaticApplyPossible: boolean;
+    blockers: MaintenancePathReason[];
+    applyBlockers: MaintenancePathReason[];
+}
+export interface MaintenancePathPolicy {
+    slug: string;
+    state: MaintenancePathState;
+    exists: boolean;
+    profile: MaintenanceProfile;
+    runMode: MaintenanceMode;
+    maintenanceModel: {
+        id: string | null;
+        configured: boolean;
+    };
+    page: {
+        role: PageRole;
+        roleSource: MaintenancePolicySource;
+        remember: RememberManagement;
+        rememberSource: MaintenancePolicySource;
+        dream: DreamManagement;
+        dreamSource: 'frontmatter' | 'default';
+        bytes: number | null;
+        reserved: boolean;
+    };
+    rules: {
+        effective: Record<string, unknown>;
+        candidates: {
+            glob: string;
+            source: string;
+        }[];
+    };
+    transformations: MaintenancePathTransformPolicy[];
+    pathIndependent: {
+        kind: Extract<MaintenanceTransform, 'observe' | 'reflect' | 'adopt'>;
+        policy: MaintenancePolicy;
+        enabled: boolean;
+        reason: string;
+    }[];
+    limits: MaintenanceLimits;
+    remainingChecks: string[];
+}
+/**
+ * Explain the default scheduled authority for one page path without inspecting page content.
+ * The answer describes permission and eligibility, not whether tonight will discover a candidate.
+ */
+export declare function explainMaintenancePath(ctx: AknoContext, rawPath: string, requestedMode?: MaintenanceMode): MaintenancePathPolicy;
+/** The page-owned structural boundary used by both planners and the explanation above. */
+export declare function pageAllowsMaintenanceTransform(config: AknoConfig, page: {
+    slug: string;
+    role: string;
+    dreamManagement: string;
+    rememberManagement?: string;
+}, kind: PageMaintenanceTransform): boolean;
+/** Exact folder allowlist semantics shared with merge candidate discovery. */
+export declare function mergePathAllowed(slug: string, folders: string[]): boolean;
+export declare function pageDeclarations(frontmatter: string): {
+    role?: PageRole;
+    remember?: RememberManagement;
+    dream?: DreamManagement;
+};
+export {};
+//# sourceMappingURL=path-policy.d.ts.map

package/dist/maintenance/path-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-policy.d.ts","sourceRoot":"","sources":["../../src/maintenance/path-policy.ts"],"names":[],"mappings":"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"}