@northtek/overstory 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,115 @@
+# OVERSTORY
+
+**A knowledge tree of your codebase where every claim carries a receipt.**
+
+> **30 seconds, no jargon:** AI tools sound exactly as confident when they're wrong as when
+> they're right. OVERSTORY reads your codebase, writes it up as short statements, and then
+> **checks every statement against the actual code** — click any one to see the exact lines
+> it came from. When the code changes, the affected statements flip to "stale" instead of
+> quietly becoming lies. Ask questions and get answers where every sentence carries a
+> checkable receipt; statements that can't be verified are withheld and say so. All of it
+> runs on your machine — your code never leaves.
+>
+> Try it: `npx @northtek/overstory build && npx @northtek/overstory serve`
+
+OVERSTORY turns any repo or docs folder into an explorable, hierarchical map — file to module
+to system — in which every statement is an atomic claim citing the exact source lines that
+support it. Citations are verified mechanically, not displayed decoratively: a claim whose
+evidence changed is marked stale, a claim whose evidence vanished is marked missing, and a
+claim with no evidence is never presented as verified.
+
+Local-first by default. With the local Ollama engine or the deterministic extractive engine
+(no LLM at all), your code never leaves your machine — air-gapped works. The Anthropic API is
+an explicit opt-in, and only then does source text leave the machine (to Anthropic, for
+summarization). The gate itself is always local.
+
+```
+npx @northtek/overstory build     # build the tree (resumable; reuses unchanged files)
+npx @northtek/overstory serve     # open the app: ask your codebase, answers notarized
+npx @northtek/overstory verify    # CI-friendly: exit 1 if any receipt fails
+npx @northtek/overstory mcp       # MCP tools for Claude Code / Cursor
+npx @northtek/overstory site      # shareable single-file explorer
+```
+
+**The app** (`overstory serve`) is a local, frontier-lab-grade answer engine over your repo:
+ask-first home, streamed phases (searching → writing → notarizing), answers with numbered
+citation chips, and receipt cards that unfold into the exact cited lines with their hash and
+verdict seal. Threads persist locally; light and dark themes; nothing leaves your machine.
+
+## Why
+
+AI tools that explain codebases have a trust problem: confident answers with citations that
+are displayed but never checked, over docs that silently rot as the code moves on. OVERSTORY
+inverts the contract:
+
+- **Receipts by construction** — the unit of storage is the claim + its cited spans, hashed
+  over the span *text* (never file positions). Edits above a span heal its line numbers;
+  edits to the evidence itself flip the claim to `STALE`.
+- **Fail-closed verdicts** — `VERIFIED` / `STALE` / `OUT_OF_CORPUS` / `UNGROUNDED`, computed
+  by a pure function against the live corpus. A forged receipt voids the claim.
+- **Honest staleness** — `overstory verify` re-checks every receipt in milliseconds and exits
+  non-zero when docs and code disagree. Docs that know when they're lying.
+- **Two disclosure tiers** — the mechanical verdict above, plus a build-time semantic
+  `faithfulness` tier from an adversarial critique pass (Reflexion-style). Claims the critic
+  rejects stay visible and flagged — abstention over confident prose, never silent deletion.
+
+**The honesty boundary, stated plainly:** verification here proves *provenance and freshness*
+(the cited lines exist and are unchanged), not truth. Semantic support is checked once at
+build time and labeled. Every claim is one click from its evidence; judge it yourself.
+
+## How it works
+
+1. **Ingest** — gitignore-aware walk, structural chunking (headings / top-level declarations).
+2. **Summarize** — each chunk becomes 3-8 atomic claims with line citations (Ollama local,
+   Anthropic API, or extractive fallback — malformed LLM output degrades per-chunk, a build
+   never dies on one bad response).
+3. **Refine** — an adversarial critique pass fact-checks each claim against its cited lines
+   (supported / unsupported), revises what it can defend, and surfaces missing facts.
+4. **Aggregate** — directory and root nodes roll up from child claims, every roll-up claim
+   citing the child claims that ground it, transitively down to source lines.
+5. **Gate** — every claim in the tree is verified; freshness is a first-class number.
+6. **Explore** — a single self-contained HTML explorer (works offline, shareable), a CLI,
+   and an MCP server.
+
+Builds are incremental and resumable: every leaf checkpoints on completion, and unchanged
+files are never re-summarized.
+
+## Hosted registry (preview)
+
+There's an experimental zero-storage registry that can show verified trees of public GitHub
+repos and re-check published trees against the live code (the registry stores nothing —
+your repo is the database). It's in quiet preview and not the point of v1: the product is
+the local tool. `overstory publish` targets it if you want to try it; details in
+docs/plans/2026-07-21-registry-design.md.
+
+## MCP: notarize your agent's answers
+
+`overstory mcp` exposes `overstory_map`, `overstory_search`, `overstory_node`, and the tool
+the others exist for — **`overstory_verify`**: your agent (Claude Code, Cursor) drafts an
+answer about the repo, submits its claims with file:line citations, and gets back per-claim
+verdicts plus the receipt text for each citation. The host model does the thinking;
+OVERSTORY checks the receipts.
+
+```json
+{ "mcpServers": { "overstory": { "command": "npx", "args": ["-y", "@northtek/overstory", "mcp"] } } }
+```
+
+## Provenance of the ideas
+
+OVERSTORY is the TypeScript synthesis of research shipped in
+[FACTGATE](https://github.com/NORTHTEKDevs/factgate) (fail-closed claim gating),
+[verified-memory](https://github.com/NORTHTEKDevs/verified-memory) (memory feeds context in,
+a gate adjudicates claims out), [GENOME](https://github.com/NORTHTEKDevs/genome)
+(hierarchical RAPTOR summarization — including the published null that tree retrieval is
+accuracy-neutral: the tree's value is the explorable provenance artifact, which is exactly
+what OVERSTORY ships), and RAIN's Reflexion loop discipline. BSHR
+(brainstorm-search-hypothesize-refine) drives the `ask` engine.
+
+## Roadmap (deliberately not in v1)
+
+Embedding search, AST-precise chunking, watch mode, a CI bot that comments when merged code
+stales the docs, team/shared trees, `claude -p` as a provider. v1 is the trustworthy core.
+
+## License
+
+Apache-2.0 © Northtek (FrostByte LLC)

package/dist/build/aggregate.d.ts

@@ -0,0 +1,9 @@
+import type { Claim, TreeNode } from '../core/types.js';
+import type { ChatProvider } from '../llm/provider.js';
+/** Deterministic roll-up: one claim per child, grounded in the child's first claim.
+ * Child detail is included only when it adds information — a child whose first claim is
+ * itself a roll-up ("Contains …") would produce noisy chains, so it is elided. */
+export declare const extractiveAggregate: (children: TreeNode[]) => Omit<Claim, 'id'>[];
+/** Interior-node claims. LLM path grounds every claim in child claim refs; invalid refs are
+ * dropped; unusable output falls back to extractive. */
+export declare const aggregateClaims: (provider: ChatProvider | null, title: string, children: TreeNode[], idPrefix: string) => Promise<Claim[]>;

package/dist/build/aggregate.js

@@ -0,0 +1,74 @@
+import { z } from 'zod';
+const aggSchema = z.object({
+    claims: z
+        .array(z.object({ text: z.string().min(3), refs: z.array(z.string()).min(1) }))
+        .min(1)
+        .max(8),
+});
+const AGG_SYSTEM = `You are the roll-up layer of a provenance-gated knowledge tree. You describe what a directory/module IS from its children's verified claims. Every claim must reference the child claims that support it. Never introduce facts absent from the children.`;
+const aggPrompt = (title, children) => {
+    const lines = [];
+    for (const child of children) {
+        lines.push(`CHILD ${child.id} (${child.title}):`);
+        for (const claim of child.claims.slice(0, 5))
+            lines.push(`  [${claim.id}] ${claim.text}`);
+    }
+    return `Summarize what "${title}" is and does in 3-6 claims for a developer seeing it for the first time. Each claim cites the child claim ids that support it.
+
+Return ONLY JSON: {"claims":[{"text":"...","refs":["<claim id>", ...]}]}
+
+${lines.join('\n')}`;
+};
+/** Deterministic roll-up: one claim per child, grounded in the child's first claim.
+ * Child detail is included only when it adds information — a child whose first claim is
+ * itself a roll-up ("Contains …") would produce noisy chains, so it is elided. */
+export const extractiveAggregate = (children) => children
+    .filter((c) => c.claims.length > 0)
+    .slice(0, 8)
+    .map((child) => {
+    const label = child.kind === 'leaf' ? child.path : `${child.title}/`;
+    const detail = child.claims[0].text;
+    const text = detail.startsWith('Contains ')
+        ? `Contains ${label} (${child.claims.length} claim${child.claims.length === 1 ? '' : 's'}).`
+        : `Contains ${label} — ${detail}`;
+    return {
+        text,
+        citations: [{ kind: 'claim', ref: { nodeId: child.id, claimId: child.claims[0].id } }],
+        faithfulness: 'supported',
+    };
+});
+/** Interior-node claims. LLM path grounds every claim in child claim refs; invalid refs are
+ * dropped; unusable output falls back to extractive. */
+export const aggregateClaims = async (provider, title, children, idPrefix) => {
+    const finish = (drafts) => drafts.map((c, i) => ({ ...c, id: `${idPrefix}#${i}` }));
+    const withClaims = children.filter((c) => c.claims.length > 0);
+    if (!provider || withClaims.length === 0)
+        return finish(extractiveAggregate(children));
+    const valid = new Map();
+    for (const child of withClaims)
+        for (const claim of child.claims)
+            valid.set(claim.id, { nodeId: child.id, claimId: claim.id });
+    try {
+        const raw = await provider.chat(aggPrompt(title, withClaims), { json: true, system: AGG_SYSTEM });
+        const first = raw.indexOf('{');
+        const last = raw.lastIndexOf('}');
+        const parsed = aggSchema.parse(JSON.parse(first >= 0 ? raw.slice(first, last + 1) : raw));
+        const drafts = [];
+        for (const d of parsed.claims) {
+            const refs = d.refs.filter((r) => valid.has(r));
+            if (refs.length === 0)
+                continue;
+            drafts.push({
+                text: d.text.trim(),
+                citations: refs.map((r) => ({ kind: 'claim', ref: valid.get(r) })),
+                faithfulness: 'unchecked',
+            });
+        }
+        if (drafts.length === 0)
+            return finish(extractiveAggregate(children));
+        return finish(drafts);
+    }
+    catch {
+        return finish(extractiveAggregate(children));
+    }
+};

package/dist/build/builder.d.ts

@@ -0,0 +1,52 @@
+import { LoadedCorpus } from '../core/corpus.js';
+import type { Tree, TreeVerification } from '../core/types.js';
+import type { ChatProvider } from '../llm/provider.js';
+export interface ProgressEvent {
+    phase: 'scan' | 'leaves' | 'aggregate' | 'verify' | 'save' | 'warn';
+    done?: number;
+    total?: number;
+    file?: string;
+    reused?: boolean;
+    message?: string;
+}
+export interface BuildOptions {
+    /** null = pure extractive build (deterministic, instant, no LLM). */
+    provider?: ChatProvider | null;
+    /** Critique model for the Reflexion pass; defaults to `provider`. */
+    critic?: ChatProvider | null;
+    /** 0 disables Reflexion. Default 1 (local models) — callers may raise for API providers. */
+    reflexionRounds?: number;
+    include?: string[];
+    maxFiles?: number;
+    name?: string;
+    onProgress?: (e: ProgressEvent) => void;
+    generator?: string;
+}
+export interface BuildResult {
+    tree: Tree;
+    verification: TreeVerification;
+    corpus: LoadedCorpus;
+    reusedLeaves: number;
+    rebuiltLeaves: number;
+    /** Non-zero means the resume guarantee was degraded during this run — surfaced, never silent. */
+    checkpointFailures: number;
+}
+export declare const dirOf: (file: string) => string;
+/** All ancestor dir paths for a set of files, deepest first (so children exist before
+ * their parent aggregates). */
+export declare const dirPaths: (files: string[]) => string[];
+/** Build (or refresh — same operation) the knowledge tree. Reuses any previous leaf whose
+ * source hash still matches, upgrades extractive leaves when an LLM provider is available,
+ * checkpoints progress after every leaf, and finishes with a full gate sweep. A killed
+ * build resumes from its partial checkpoint on the next run. */
+export declare const buildTree: (root: string, opts?: BuildOptions) => Promise<BuildResult>;
+export interface VerifyResult {
+    tree: Tree;
+    verification: TreeVerification;
+    staleFiles: string[];
+}
+/** Read-only verification of an existing tree against the live corpus. Applies verdicts and
+ * healed positions in-memory; never writes. Null when no tree exists. The corpus is loaded
+ * with the OPTIONS THE TREE WAS BUILT WITH (caller may override) — verifying against a
+ * differently-scoped corpus yields wrong verdicts. */
+export declare const verifyExisting: (root: string, opts?: Pick<BuildOptions, 'include' | 'maxFiles'>) => Promise<VerifyResult | null>;