app/engine/ladder.ts

 // The real Ladder shape (see site/content/ladder-design/). The repo's file

 // and directory tree is the backbone everything else pivots on:

 // repo -> directory -> file -> function -> lines, a containment hierarchy.

 //

 // Two kinds of rung don't fit that tree:

 // - Repo-level artifacts that aren't shaped like a file (a release, the

 // package itself) hang directly off the repo rung instead of nesting

 // in the directory tree.

 // - Asks are thread-shaped, not containment-shaped: whatever follows an

 // ASK (an ANSWER resolving it, or a further ASK raising something new

 // in the same thread) is a child rung of it, in order. There's no

 // separate "issue" or "comment" concept: a GitHub issue being filed is

 // someone ASKing the Maintainer about something, and a reply is either

 // an ANSWER or another ASK, exactly the same vocabulary native zz

 // activity uses. Onboarding doesn't get its own shape; it's the same

 // protocol, read from a different source. An ask that relates to

 // specific files doesn't contain them; it's referenced as a `source`

 // on those files' own rungs, and separately has its own full rung

 // (with its thread) living at the repo level.

 //

 // Storage: git notes, one per rung anchored to a real git object (a file's

 // blob, a directory's tree, the repo's root tree, the repo's root commit

 // for an ask, or the commit a release is tied to), not one blob for the

 // whole tree or one file per rung on disk. See engine/ladderNotes.ts and

 // engine/gitNotes.ts. This file only defines the authoring shape: build a

 // Rung tree with children nested inline, and ladderNotes.ts figures out

 // what gets its own note versus what's embedded in its nearest anchor

 // ancestor.

 export type RungKind =

  | "repo"

  | "directory"

  | "file"

  | "function"

  | "lines"

  | "release"

  | "package"

  | "ask"

  | "answer"

  | "contributor"

  | "dependencies"

  // Historical changelog: one changeset per commit, replayed in order.

  // A changeset's filechange children are embedded in its one note, not

  // separate anchors -- they're only ever read as part of that commit's

  // record, never addressed independently. Distinct from the `file` kind

  // above, which tracks a file's *current* state at HEAD, kept up to date

  // by the coordinator as changesets land, not the file's full history.

  | "changeset"

  | "filechange"

  | "linechange";

 export interface RungSource {

  kind: "commit" | "pr" | "issue";

  ref: string;

  title: string;

  author: string;

  at: string;

 }

 export interface Rung {

  path: string;

  kind: RungKind;

  summary: string;

  sources: RungSource[];

  /** Paths of other rungs this one relates to without containing them, e.g. an ask's related files. */

  touches?: string[];

  children: Rung[];

 }

 /** The repo root rung's path. Not "." since paths double as git note lookup keys and filenames elsewhere. */

 export const REPO_RUNG_PATH = "_repo";