@tenphi/akno-core 0.1.0

package/dist/maintenance/semantic-merge-discovery.js

@@ -0,0 +1,308 @@
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import { parsePage } from "../kb/page.js";
+import { sha256 } from "../store/ids.js";
+import { judgeSemanticMergeCandidate, SEMANTIC_MERGE_MAX_PAGE_CHARS, SEMANTIC_MERGE_EMBEDDING_VERSION, SEMANTIC_MERGE_PREFILTER_THRESHOLD, SEMANTIC_MERGE_PROMPT_VERSION, SEMANTIC_MERGE_SIGNATURE_VERSION, } from "./merge-classifier.js";
+/**
+ * Similarity creates a bounded queue; only the strict classifier can emit a candidate. Exact
+ * content/model/prompt fingerprints cache both outcomes without retaining text or rationale.
+ */
+export async function discoverSemanticMergeCandidates(ctx, sources, options) {
+    const metrics = emptySemanticMergeDiscoveryMetrics(sources.length);
+    const empty = () => ({
+        pairs: [],
+        degraded: [],
+        warnings: [],
+        metrics,
+    });
+    if (sources.length < 2 || options.candidateLimit <= 0)
+        return empty();
+    if (!ctx.models.embedding.available) {
+        return {
+            ...empty(),
+            degraded: [{ reason: 'no_embedding_model', failure: 'unavailable' }],
+        };
+    }
+    if (!ctx.models.derive.available) {
+        return {
+            ...empty(),
+            degraded: [{ reason: 'no_derive_model', failure: 'unavailable' }],
+        };
+    }
+    const embeddingEndpoint = ctx.models.embedding.endpointFingerprint;
+    const prepared = [];
+    let oversize = 0;
+    let unreadable = 0;
+    for (const source of sources) {
+        if (source.bytes > SEMANTIC_MERGE_MAX_PAGE_CHARS * 4) {
+            oversize++;
+            continue;
+        }
+        const content = await fsp
+            .readFile(path.join(ctx.config.aknoPath, source.relPath), 'utf8')
+            .catch(() => null);
+        if (content === null) {
+            unreadable++;
+            continue;
+        }
+        const parsed = parsePage(source.relPath, content);
+        const body = parsed.body.trim();
+        if (body.length === 0 || body.length > SEMANTIC_MERGE_MAX_PAGE_CHARS) {
+            oversize++;
+            continue;
+        }
+        const embeddingText = /^#\s+/m.test(body) ? body : `# ${source.title}\n\n${body}`;
+        const modelPage = { slug: source.slug, title: source.title, content: body };
+        const sourceHash = sha256(embeddingText);
+        prepared.push({
+            source,
+            embeddingText,
+            embeddingFingerprint: embeddingFingerprint(source.id, sourceHash, embeddingEndpoint),
+            semanticInputHash: sha256(JSON.stringify(modelPage)),
+            modelPage,
+        });
+    }
+    metrics.pagesPrepared = prepared.length;
+    metrics.pagesSkipped = oversize + unreadable;
+    const warnings = [
+        ...(oversize > 0
+            ? [
+                `semantic merge discovery skipped ${oversize} page(s) outside the ${SEMANTIC_MERGE_MAX_PAGE_CHARS}-character complete-page limit`,
+            ]
+            : []),
+        ...(unreadable > 0 ? [`semantic merge discovery could not read ${unreadable} eligible page(s)`] : []),
+    ];
+    if (prepared.length < 2)
+        return { ...empty(), warnings };
+    const vectors = new Array(prepared.length);
+    const missingIndexes = [];
+    const readEmbedding = ctx.store.db.prepare('SELECT dimensions, embedding FROM semantic_merge_embeddings WHERE fingerprint = ?');
+    const expectedDimensions = ctx.config.models.embedding.dimensions ?? ctx.store.vectors.dimensions;
+    for (const [index, entry] of prepared.entries()) {
+        const cached = readEmbedding.get(entry.embeddingFingerprint);
+        const vector = cached ? decodeEmbedding(cached, expectedDimensions) : null;
+        if (vector) {
+            vectors[index] = vector;
+            metrics.embeddingCacheHits++;
+        }
+        else {
+            missingIndexes.push(index);
+        }
+    }
+    metrics.embeddingInputs = missingIndexes.length;
+    const batchSize = Math.max(1, ctx.config.models.embedding.batch ?? 32);
+    const writeEmbedding = ctx.store.readOnly
+        ? null
+        : ctx.store.db.prepare(`INSERT OR REPLACE INTO semantic_merge_embeddings(
+           fingerprint, page_id, source_hash, embedding_endpoint, signature_version,
+           dimensions, embedding, created_at
+         ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`);
+    const deleteStaleEmbedding = ctx.store.readOnly
+        ? null
+        : ctx.store.db.prepare('DELETE FROM semantic_merge_embeddings WHERE page_id = ? AND fingerprint != ?');
+    for (let offset = 0; offset < missingIndexes.length; offset += batchSize) {
+        const batchIndexes = missingIndexes.slice(offset, offset + batchSize);
+        const batch = batchIndexes.map((index) => prepared[index]);
+        metrics.embeddingCalls++;
+        const embedded = await ctx.models.embedding.embed(batch.map((entry) => entry.embeddingText));
+        if (!embedded.ok || !embedded.value) {
+            return {
+                pairs: [],
+                warnings,
+                metrics,
+                degraded: [
+                    {
+                        reason: ctx.models.embedding.degradedReason(embedded),
+                        failure: embedded.reason ?? 'request_failed',
+                    },
+                ],
+            };
+        }
+        const returnedVectors = Array.from({ length: batch.length }, (_, index) => embedded.value[index]);
+        if (embedded.value.length !== batch.length ||
+            returnedVectors.some((vector) => !vector || vector.length !== expectedDimensions)) {
+            ctx.models.embedding.reportInvalidResponse();
+            return {
+                pairs: [],
+                warnings,
+                metrics,
+                degraded: [{ reason: 'embedding_failed', failure: 'bad_response' }],
+            };
+        }
+        const createdAt = new Date().toISOString();
+        const retainBatch = () => {
+            for (const [batchIndex, returnedVector] of returnedVectors.entries()) {
+                const vector = returnedVector;
+                const preparedIndex = batchIndexes[batchIndex];
+                const entry = prepared[preparedIndex];
+                vectors[preparedIndex] = vector;
+                deleteStaleEmbedding?.run(entry.source.id, entry.embeddingFingerprint);
+                writeEmbedding?.run(entry.embeddingFingerprint, entry.source.id, sha256(entry.embeddingText), embeddingEndpoint, SEMANTIC_MERGE_EMBEDDING_VERSION, vector.length, encodeEmbedding(vector), createdAt);
+            }
+        };
+        if (writeEmbedding)
+            ctx.store.transaction(retainBatch);
+        else
+            retainBatch();
+    }
+    const scored = [];
+    for (let leftIndex = 0; leftIndex < prepared.length; leftIndex++) {
+        for (let rightIndex = leftIndex + 1; rightIndex < prepared.length; rightIndex++) {
+            const left = prepared[leftIndex];
+            const right = prepared[rightIndex];
+            if (path.posix.dirname(left.source.slug) !== path.posix.dirname(right.source.slug))
+                continue;
+            if (options.excludedPairKeys.has(semanticMergePairKey(left.source.id, right.source.id)))
+                continue;
+            metrics.pairsCompared++;
+            const score = cosine(vectors[leftIndex], vectors[rightIndex]);
+            if (Number.isFinite(score) && score >= SEMANTIC_MERGE_PREFILTER_THRESHOLD) {
+                scored.push({ left, right, score });
+            }
+        }
+    }
+    metrics.prefilteredPairs = scored.length;
+    scored.sort((left, right) => right.score - left.score ||
+        semanticMergePairKey(left.left.source.id, left.right.source.id).localeCompare(semanticMergePairKey(right.left.source.id, right.right.source.id)));
+    const classifierEndpoint = ctx.models.derive.endpointFingerprint;
+    const readCached = ctx.store.db.prepare('SELECT outcome FROM semantic_merge_verdicts WHERE fingerprint = ?');
+    const writeCached = ctx.store.readOnly
+        ? null
+        : ctx.store.db.prepare(`INSERT OR REPLACE INTO semantic_merge_verdicts(
+           fingerprint, left_page, right_page, score, outcome, embedding_endpoint,
+           classifier_endpoint, prompt_version, signature_version, created_at
+         ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+    const deleteStaleVerdict = ctx.store.readOnly
+        ? null
+        : ctx.store.db.prepare(`DELETE FROM semantic_merge_verdicts
+          WHERE left_page = ? AND right_page = ? AND fingerprint != ?`);
+    const pairs = [];
+    const degraded = [];
+    const classifierCandidates = scored.slice(0, options.candidateLimit);
+    metrics.classifierCandidates = classifierCandidates.length;
+    for (const pair of classifierCandidates) {
+        const ordered = [pair.left, pair.right].sort((left, right) => left.source.id.localeCompare(right.source.id));
+        const fingerprint = verdictFingerprint(ordered[0], ordered[1], embeddingEndpoint, classifierEndpoint);
+        const cached = readCached.get(fingerprint);
+        let outcome = cached?.outcome ?? null;
+        let decisionSource = 'cache';
+        if (outcome) {
+            metrics.classifierCacheHits++;
+        }
+        else {
+            decisionSource = 'model';
+            metrics.classifierCalls++;
+            const judged = await judgeSemanticMergeCandidate(ctx.models.derive, pair.left.modelPage, pair.right.modelPage);
+            if (!judged.ok || !judged.value) {
+                degraded.push({
+                    reason: ctx.models.derive.degradedReason(judged),
+                    failure: judged.reason ?? 'bad_response',
+                });
+                continue;
+            }
+            outcome = judged.value.outcome;
+            deleteStaleVerdict?.run(ordered[0].source.id, ordered[1].source.id, fingerprint);
+            writeCached?.run(fingerprint, ordered[0].source.id, ordered[1].source.id, pair.score, outcome, embeddingEndpoint, classifierEndpoint, SEMANTIC_MERGE_PROMPT_VERSION, SEMANTIC_MERGE_SIGNATURE_VERSION, new Date().toISOString());
+        }
+        if (outcome !== 'same_subject')
+            continue;
+        metrics.qualifiedPairs++;
+        const [canonical, duplicate] = [pair.left.source, pair.right.source].sort((left, right) => right.bytes - left.bytes || left.slug.localeCompare(right.slug));
+        pairs.push({ canonical: canonical, duplicate: duplicate, score: pair.score, decisionSource });
+    }
+    return { pairs, degraded, warnings, metrics };
+}
+function emptySemanticMergeDiscoveryMetrics(pagesConsidered = 0) {
+    return {
+        pagesConsidered,
+        pagesPrepared: 0,
+        pagesSkipped: 0,
+        embeddingCacheHits: 0,
+        embeddingInputs: 0,
+        embeddingCalls: 0,
+        pairsCompared: 0,
+        prefilteredPairs: 0,
+        classifierCandidates: 0,
+        classifierCacheHits: 0,
+        classifierCalls: 0,
+        qualifiedPairs: 0,
+    };
+}
+export function addSemanticMergeDiscoveryMetrics(current, next) {
+    if (!current)
+        return next ? { ...next } : null;
+    if (!next)
+        return { ...current };
+    return {
+        pagesConsidered: current.pagesConsidered + next.pagesConsidered,
+        pagesPrepared: current.pagesPrepared + next.pagesPrepared,
+        pagesSkipped: current.pagesSkipped + next.pagesSkipped,
+        embeddingCacheHits: current.embeddingCacheHits + next.embeddingCacheHits,
+        embeddingInputs: current.embeddingInputs + next.embeddingInputs,
+        embeddingCalls: current.embeddingCalls + next.embeddingCalls,
+        pairsCompared: current.pairsCompared + next.pairsCompared,
+        prefilteredPairs: current.prefilteredPairs + next.prefilteredPairs,
+        classifierCandidates: current.classifierCandidates + next.classifierCandidates,
+        classifierCacheHits: current.classifierCacheHits + next.classifierCacheHits,
+        classifierCalls: current.classifierCalls + next.classifierCalls,
+        qualifiedPairs: current.qualifiedPairs + next.qualifiedPairs,
+    };
+}
+export function semanticMergePairKey(leftId, rightId) {
+    return [leftId, rightId].sort().join('|');
+}
+function verdictFingerprint(left, right, embeddingEndpoint, classifierEndpoint) {
+    return sha256(JSON.stringify({
+        signatureVersion: SEMANTIC_MERGE_SIGNATURE_VERSION,
+        promptVersion: SEMANTIC_MERGE_PROMPT_VERSION,
+        threshold: SEMANTIC_MERGE_PREFILTER_THRESHOLD,
+        embeddingEndpoint,
+        classifierEndpoint,
+        pages: [
+            { id: left.source.id, semanticInputHash: left.semanticInputHash },
+            { id: right.source.id, semanticInputHash: right.semanticInputHash },
+        ],
+    }));
+}
+function embeddingFingerprint(pageId, sourceHash, embeddingEndpoint) {
+    return sha256(JSON.stringify({
+        signatureVersion: SEMANTIC_MERGE_EMBEDDING_VERSION,
+        embeddingEndpoint,
+        pageId,
+        sourceHash,
+    }));
+}
+function encodeEmbedding(vector) {
+    const buffer = Buffer.allocUnsafe(vector.length * 4);
+    for (let index = 0; index < vector.length; index++)
+        buffer.writeFloatLE(vector[index], index * 4);
+    return buffer;
+}
+function decodeEmbedding(row, expectedDimensions) {
+    if (row.dimensions !== expectedDimensions ||
+        !Buffer.isBuffer(row.embedding) ||
+        row.embedding.byteLength !== expectedDimensions * 4) {
+        return null;
+    }
+    const vector = new Float32Array(expectedDimensions);
+    for (let index = 0; index < expectedDimensions; index++) {
+        const value = row.embedding.readFloatLE(index * 4);
+        if (!Number.isFinite(value))
+            return null;
+        vector[index] = value;
+    }
+    return vector;
+}
+function cosine(left, right) {
+    let dot = 0;
+    let leftNorm = 0;
+    let rightNorm = 0;
+    const length = Math.min(left.length, right.length);
+    for (let index = 0; index < length; index++) {
+        dot += left[index] * right[index];
+        leftNorm += left[index] * left[index];
+        rightNorm += right[index] * right[index];
+    }
+    return leftNorm === 0 || rightNorm === 0 ? 0 : dot / Math.sqrt(leftNorm * rightNorm);
+}
+//# sourceMappingURL=semantic-merge-discovery.js.map

package/dist/maintenance/semantic-merge-discovery.js.map

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

package/dist/maintenance/temporal.d.ts

@@ -0,0 +1,44 @@
+export interface TemporalMetadata {
+    kind: 'event';
+    start?: string;
+    until: string;
+    timezone?: string;
+}
+export interface TemporalClock {
+    now: string;
+    timezone: string;
+    localDate: string;
+}
+export interface TemporalInferenceInput {
+    slug: string;
+    title: string;
+    frontmatter: Record<string, unknown>;
+    body: string;
+}
+export interface TemporalDeclaration {
+    metadata: TemporalMetadata | null;
+    disabled: boolean;
+    invalid: boolean;
+}
+export declare function temporalClock(now?: Date, timezone?: string): TemporalClock;
+export declare function readTemporalDeclaration(frontmatter: Record<string, unknown>): TemporalDeclaration;
+/**
+ * Infers only boundaries whose complete date is already present in structured metadata, a
+ * date-range slug, or nearby event language. It never turns the latest historical date on an
+ * evergreen subject page into that page's expiry date.
+ */
+export declare function inferTemporalMetadata(input: TemporalInferenceInput): TemporalMetadata | null;
+/** Date candidates are passed to the model, which may select one but may not invent another. */
+export declare function temporalBoundaryCandidates(input: TemporalInferenceInput): string[];
+export declare function cleanTemporalProposal(value: unknown, candidates: string[]): {
+    metadata: TemporalMetadata | null;
+    issue: string | null;
+};
+export declare function temporalState(metadata: TemporalMetadata, clock: TemporalClock): 'active' | 'past';
+export declare function temporalPrompt(metadata: TemporalMetadata | null, clock: TemporalClock): string;
+/**
+ * Adds only Akno's own temporal key without parsing and re-emitting the rest of the YAML.
+ * An unusual inline `akno: {...}` declaration is left for a human rather than duplicated.
+ */
+export declare function withTemporalMetadata(content: string, metadata: TemporalMetadata): string | null;
+//# sourceMappingURL=temporal.d.ts.map

package/dist/maintenance/temporal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"temporal.d.ts","sourceRoot":"","sources":["../../src/maintenance/temporal.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAClC,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;CAClB;AAiCD,wBAAgB,aAAa,CAAC,GAAG,OAAa,EAAE,QAAQ,SAAmB,GAAG,aAAa,CAM1F;AAED,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,mBAAmB,CAQjG;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,sBAAsB,GAAG,gBAAgB,GAAG,IAAI,CAiB5F;AAED,gGAAgG;AAChG,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,sBAAsB,GAAG,MAAM,EAAE,CAclF;AAED,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,OAAO,EACd,UAAU,EAAE,MAAM,EAAE,GACnB;IAAE,QAAQ,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAe7D;AAED,wBAAgB,aAAa,CAAC,QAAQ,EAAE,gBAAgB,EAAE,KAAK,EAAE,aAAa,GAAG,QAAQ,GAAG,MAAM,CAMjG;AAED,wBAAgB,cAAc,CAAC,QAAQ,EAAE,gBAAgB,GAAG,IAAI,EAAE,KAAK,EAAE,aAAa,GAAG,MAAM,CAQ9F;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,gBAAgB,GAAG,MAAM,GAAG,IAAI,CAoB/F"}

package/dist/maintenance/temporal.js

@@ -0,0 +1,295 @@
+import { parseFrontmatter } from "../kb/frontmatter.js";
+const MONTHS = new Map([
+    ['january', 1],
+    ['february', 2],
+    ['march', 3],
+    ['april', 4],
+    ['may', 5],
+    ['june', 6],
+    ['july', 7],
+    ['august', 8],
+    ['september', 9],
+    ['october', 10],
+    ['november', 11],
+    ['december', 12],
+    ['jan', 1],
+    ['feb', 2],
+    ['mar', 3],
+    ['apr', 4],
+    ['jun', 6],
+    ['jul', 7],
+    ['aug', 8],
+    ['sep', 9],
+    ['sept', 9],
+    ['oct', 10],
+    ['nov', 11],
+    ['dec', 12],
+]);
+const MONTH_PATTERN = 'January|February|March|April|May|June|July|August|September|October|November|December|Jan|Feb|Mar|Apr|Jun|Jul|Aug|Sep|Sept|Oct|Nov|Dec';
+const EVENT_LANGUAGE = /\b(?:event|trip|travel|vacation|visit|concert|conference|appointment|stay|itinerary)\b/i;
+export function temporalClock(now = new Date(), timezone = systemTimezone()) {
+    return {
+        now: now.toISOString(),
+        timezone,
+        localDate: dateInTimezone(now, timezone),
+    };
+}
+export function readTemporalDeclaration(frontmatter) {
+    const akno = objectValue(frontmatter.akno);
+    if (!akno || !Object.hasOwn(akno, 'temporal')) {
+        return { metadata: null, disabled: false, invalid: false };
+    }
+    if (akno.temporal === false)
+        return { metadata: null, disabled: true, invalid: false };
+    const metadata = cleanTemporal(akno.temporal);
+    return { metadata, disabled: false, invalid: metadata === null };
+}
+/**
+ * Infers only boundaries whose complete date is already present in structured metadata, a
+ * date-range slug, or nearby event language. It never turns the latest historical date on an
+ * evergreen subject page into that page's expiry date.
+ */
+export function inferTemporalMetadata(input) {
+    const declaration = readTemporalDeclaration(input.frontmatter);
+    if (declaration.metadata || declaration.disabled || declaration.invalid)
+        return declaration.metadata;
+    const timezone = readTimezone(input.frontmatter);
+    const dates = typeof input.frontmatter.dates === 'string' ? input.frontmatter.dates : '';
+    const structured = isoRange(dates);
+    if (structured)
+        return withTimezone(structured, timezone);
+    const text = `${input.title}\n${input.body.slice(0, 12_000)}`;
+    const proseRange = rangeNearEventLanguage(text);
+    if (proseRange)
+        return withTimezone(proseRange, timezone);
+    // Filenames are useful structure but can outlive a changed itinerary. Page-authored dates
+    // therefore outrank the slug, which is the safe fallback rather than the authority.
+    const slugRange = rangeFromSlug(input.slug);
+    return slugRange ? withTimezone(slugRange, timezone) : null;
+}
+/** Date candidates are passed to the model, which may select one but may not invent another. */
+export function temporalBoundaryCandidates(input) {
+    const out = new Set();
+    const add = (metadata) => {
+        if (!metadata)
+            return;
+        if (metadata.start)
+            out.add(datePart(metadata.start));
+        out.add(datePart(metadata.until));
+    };
+    add(isoRange(typeof input.frontmatter.dates === 'string' ? input.frontmatter.dates : ''));
+    add(rangeFromSlug(input.slug));
+    add(rangeNearEventLanguage(`${input.title}\n${input.body.slice(0, 12_000)}`));
+    for (const match of `${input.title}\n${input.body.slice(0, 12_000)}`.matchAll(/\b\d{4}-\d{2}-\d{2}\b/g)) {
+        if (validDate(match[0]))
+            out.add(match[0]);
+    }
+    return [...out].sort();
+}
+export function cleanTemporalProposal(value, candidates) {
+    if (value === undefined || value === null || value === false)
+        return { metadata: null, issue: null };
+    const metadata = cleanTemporal(value);
+    if (!metadata)
+        return { metadata: null, issue: 'the proposed temporal boundary is malformed' };
+    const allowed = new Set(candidates);
+    if (!allowed.has(datePart(metadata.until))) {
+        return { metadata: null, issue: `the proposed event end is not supplied by the page: ${metadata.until}` };
+    }
+    if (metadata.start && !allowed.has(datePart(metadata.start))) {
+        return {
+            metadata: null,
+            issue: `the proposed event start is not supplied by the page: ${metadata.start}`,
+        };
+    }
+    return { metadata, issue: null };
+}
+export function temporalState(metadata, clock) {
+    if (isDate(metadata.until)) {
+        const local = dateInTimezone(new Date(clock.now), metadata.timezone ?? clock.timezone);
+        return local > metadata.until ? 'past' : 'active';
+    }
+    return Date.parse(clock.now) > Date.parse(metadata.until) ? 'past' : 'active';
+}
+export function temporalPrompt(metadata, clock) {
+    const lines = [`Current time: ${clock.now}`, `System timezone: ${clock.timezone}`];
+    if (metadata) {
+        lines.push(`Temporal page: event`, ...(metadata.start ? [`Starts: ${metadata.start}`] : []));
+        lines.push(`Ends: ${metadata.until}`, `Temporal state: ${temporalState(metadata, clock)}`);
+        if (metadata.timezone)
+            lines.push(`Event timezone: ${metadata.timezone}`);
+    }
+    return lines.join('\n');
+}
+/**
+ * Adds only Akno's own temporal key without parsing and re-emitting the rest of the YAML.
+ * An unusual inline `akno: {...}` declaration is left for a human rather than duplicated.
+ */
+export function withTemporalMetadata(content, metadata) {
+    const fm = parseFrontmatter(content);
+    const declaration = readTemporalDeclaration(fm.data);
+    if (declaration.metadata || declaration.disabled || declaration.invalid)
+        return content;
+    const block = temporalYaml(metadata);
+    if (!fm.present)
+        return `---\nakno:\n${block}---\n\n${content}`;
+    const head = content.slice(0, fm.bodyOffset);
+    const akno = /^akno:[ \t]*\r?$/m.exec(head);
+    if (akno?.index !== undefined) {
+        const newline = head.indexOf('\n', akno.index);
+        if (newline < 0)
+            return null;
+        return `${head.slice(0, newline + 1)}${block}${head.slice(newline + 1)}${content.slice(fm.bodyOffset)}`;
+    }
+    if (objectValue(fm.data.akno))
+        return null;
+    const close = head.lastIndexOf('---');
+    if (close <= 0)
+        return null;
+    return `${head.slice(0, close)}akno:\n${block}${head.slice(close)}${content.slice(fm.bodyOffset)}`;
+}
+function temporalYaml(metadata) {
+    return (`  temporal:\n` +
+        `    kind: event\n` +
+        (metadata.start ? `    start: ${JSON.stringify(metadata.start)}\n` : '') +
+        `    until: ${JSON.stringify(metadata.until)}\n` +
+        (metadata.timezone ? `    timezone: ${JSON.stringify(metadata.timezone)}\n` : ''));
+}
+function cleanTemporal(value) {
+    const record = objectValue(value);
+    if (!record || record.kind !== 'event' || typeof record.until !== 'string')
+        return null;
+    const until = cleanBoundary(record.until);
+    const start = typeof record.start === 'string' ? cleanBoundary(record.start) : null;
+    if (!until || (typeof record.start === 'string' && !start))
+        return null;
+    if (start && Date.parse(boundaryInstant(start, false)) > Date.parse(boundaryInstant(until, true)))
+        return null;
+    const timezone = typeof record.timezone === 'string' && validTimezone(record.timezone) ? record.timezone : null;
+    return {
+        kind: 'event',
+        ...(start ? { start } : {}),
+        until,
+        ...(timezone ? { timezone } : {}),
+    };
+}
+function cleanBoundary(value) {
+    if (isDate(value))
+        return validDate(value) ? value : null;
+    if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d{1,3})?)?(?:Z|[+-]\d{2}:\d{2})$/.test(value)) {
+        return null;
+    }
+    return Number.isNaN(Date.parse(value)) ? null : value;
+}
+function isoRange(text) {
+    const match = /(\d{4}-\d{2}-\d{2})\s*(?:to|through|[-–‑—])\s*(\d{4}-\d{2}-\d{2})/i.exec(text);
+    if (!match || !validDate(match[1]) || !validDate(match[2]))
+        return null;
+    return orderedRange(match[1], match[2]);
+}
+function rangeFromSlug(slug) {
+    const basename = slug.split('/').at(-1) ?? slug;
+    const match = /^(\d{4})-(\d{2})-(\d{2})-(\d{2})(?:-|$)/.exec(basename);
+    if (!match)
+        return null;
+    const year = Number(match[1]);
+    const month = Number(match[2]);
+    const first = Number(match[3]);
+    const last = Number(match[4]);
+    const start = ymd(year, month, first);
+    const endDate = new Date(Date.UTC(year, month - 1 + (last < first ? 1 : 0), last));
+    const until = endDate.toISOString().slice(0, 10);
+    return start && validDate(until) ? orderedRange(start, until) : null;
+}
+function rangeNearEventLanguage(text) {
+    const sameMonth = new RegExp(`\\b(${MONTH_PATTERN})\\s+(\\d{1,2})\\s*[-–‑—]\\s*(\\d{1,2})(?:,)?\\s+(\\d{4})\\b`, 'i');
+    const crossMonth = new RegExp(`\\b(${MONTH_PATTERN})\\s+(\\d{1,2})\\s*[-–‑—]\\s*(${MONTH_PATTERN})\\s+(\\d{1,2})(?:,)?\\s+(\\d{4})\\b`, 'i');
+    for (const pattern of [crossMonth, sameMonth]) {
+        const match = pattern.exec(text);
+        if (!match || match.index === undefined)
+            continue;
+        const nearby = text.slice(Math.max(0, match.index - 100), match.index + match[0].length + 100);
+        if (!EVENT_LANGUAGE.test(nearby))
+            continue;
+        if (pattern === crossMonth) {
+            const year = Number(match[5]);
+            const start = ymd(year, monthNumber(match[1]), Number(match[2]));
+            const until = ymd(year, monthNumber(match[3]), Number(match[4]));
+            if (start && until)
+                return orderedRange(start, until);
+        }
+        else {
+            const year = Number(match[4]);
+            const month = monthNumber(match[1]);
+            const start = ymd(year, month, Number(match[2]));
+            const until = ymd(year, month, Number(match[3]));
+            if (start && until)
+                return orderedRange(start, until);
+        }
+    }
+    return null;
+}
+function orderedRange(start, until) {
+    return Date.parse(`${start}T00:00:00Z`) <= Date.parse(`${until}T23:59:59Z`)
+        ? { kind: 'event', start, until }
+        : null;
+}
+function withTimezone(metadata, timezone) {
+    return timezone ? { ...metadata, timezone } : metadata;
+}
+function readTimezone(frontmatter) {
+    const value = frontmatter.timezone;
+    return typeof value === 'string' && validTimezone(value) ? value : null;
+}
+function monthNumber(value) {
+    return MONTHS.get(value.toLowerCase()) ?? 0;
+}
+function ymd(year, month, day) {
+    if (!Number.isInteger(year) || !Number.isInteger(month) || !Number.isInteger(day))
+        return null;
+    const value = `${String(year).padStart(4, '0')}-${String(month).padStart(2, '0')}-${String(day).padStart(2, '0')}`;
+    return validDate(value) ? value : null;
+}
+function validDate(value) {
+    if (!isDate(value))
+        return false;
+    const parsed = new Date(`${value}T00:00:00Z`);
+    return !Number.isNaN(parsed.getTime()) && parsed.toISOString().slice(0, 10) === value;
+}
+function isDate(value) {
+    return /^\d{4}-\d{2}-\d{2}$/.test(value);
+}
+function datePart(value) {
+    return value.slice(0, 10);
+}
+function boundaryInstant(value, endOfDay) {
+    return isDate(value) ? `${value}T${endOfDay ? '23:59:59' : '00:00:00'}Z` : value;
+}
+function objectValue(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : null;
+}
+function systemTimezone() {
+    return Intl.DateTimeFormat().resolvedOptions().timeZone || 'UTC';
+}
+function validTimezone(value) {
+    try {
+        new Intl.DateTimeFormat('en', { timeZone: value }).format();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function dateInTimezone(value, timezone) {
+    const parts = new Intl.DateTimeFormat('en-CA', {
+        timeZone: timezone,
+        year: 'numeric',
+        month: '2-digit',
+        day: '2-digit',
+    }).formatToParts(value);
+    const part = (type) => parts.find((entry) => entry.type === type)?.value ?? '';
+    return `${part('year')}-${part('month')}-${part('day')}`;
+}
+//# sourceMappingURL=temporal.js.map