@looply/sdk 0.0.0-stage → 0.1.0

package/dist/views.d.ts

@@ -0,0 +1,701 @@
+/**
+ * WHAT AN EXTERNAL CLIENT IS PROMISED, AND NOTHING ELSE.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * 🔴 WHITELISTS, NOT PASS-THROUGHS.
+ *
+ * Every type here names its fields. None is `Row & {…}`, none spreads a
+ * database record, and none is an alias for a domain type that might grow. That
+ * is the whole point: a field added to a Prisma model or to `@looply/core` must
+ * not become part of a public contract because somebody widened a type
+ * elsewhere. It becomes public when it is written down here, deliberately.
+ *
+ * `contract.spec.ts` asserts the field SETS, so a silent addition fails a test
+ * rather than shipping.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * 🔴 PROVIDER-NEUTRAL BY CONSTRUCTION
+ *
+ * No field here is named for a provider, and none carries a session id, a tool
+ * name, a permission mode or an MCP concept. An external client integrating
+ * Looply is buying "governed autonomous work on a repository"; which model
+ * performs it is Looply's business and may change under them.
+ *
+ * ⚠️ `provider` and `model` may appear one day as DIAGNOSTICS. They are absent
+ * now rather than optional, because an optional field is one a client starts
+ * depending on.
+ */
+export interface ProjectView {
+    readonly id: string;
+    readonly name: string;
+    /**
+     * ⚠️ NO LOCAL PATH. Where the repository sits on somebody's disk is a fact
+     * about their machine, contains their account name, and is of no use to a
+     * client that cannot reach that disk anyway.
+     */
+    readonly createdAt: string;
+}
+/**
+ * ⚠️ THERE IS NO `met` STATE, AND AN SDK THAT OFFERED ONE WOULD BE LYING.
+ *
+ * A goal is `draft` until somebody chooses to pursue it, `active` while it is
+ * pursued, and `abandoned` if they give up on it. "Met" is not recorded: whether
+ * an intention was satisfied is a judgement a person makes by looking at the
+ * work, not a column, and inventing one here would promise a client a fact the
+ * server does not have.
+ *
+ * 🔴 `draft` IS THE STATE A NEW GOAL IS BORN IN. A client that renders only
+ * `active` will show nothing after a successful `createGoal`.
+ */
+export type GoalStateView = 'draft' | 'active' | 'abandoned';
+/** One requirement or constraint of a stored source a goal serves. */
+export interface RequirementLinkView {
+    readonly sourceId: string;
+    /** The statement's ordinal within the source. */
+    readonly ordinal: number;
+}
+export interface GoalView {
+    readonly id: string;
+    readonly projectId: string;
+    /** The person's own wording, preserved verbatim. Never a summary. */
+    readonly text: string;
+    readonly state: GoalStateView;
+    /**
+     * The optimistic-concurrency token AND the identity of the intent.
+     *
+     * Amending the wording bumps it, so a client holding version 3 is holding a
+     * different question from one holding version 4 — which is why every
+     * version-scoped answer below carries it too.
+     */
+    readonly version: number;
+    /** The caller's own key for the creation attempt. See `createGoal`. */
+    readonly clientRef: string;
+    readonly createdAt: string;
+    /**
+     * "B after A": ids of goals of the same project this one waits for. Always
+     * present, empty when none. The machine will not start this goal while one
+     * of them is outstanding; a cycle is refused at write time, named.
+     */
+    readonly dependsOn: readonly string[];
+    /**
+     * Repository regions a run bound to this goal may write to, canonical
+     * (`packages/orders`, never `./Packages/Orders/`). With `run.surfaces` on,
+     * the machine takes a lease for exactly these before any work, and a second
+     * run on one of them waits. Always present, empty when none.
+     */
+    readonly surfaces: readonly string[];
+    /** Which requirements and constraints of the project's sources this goal serves. Always present, empty when none. */
+    readonly requirements: readonly RequirementLinkView[];
+    /**
+     * DERIVED, never stored: the keys `<sourceId>#<ordinal>` of the linked
+     * requirements a person attested `implemented-and-evidenced` at the tree of
+     * the latest measurement. Present on `goal()`, absent on `goals()`. No
+     * client can write it and no rule produces it.
+     */
+    readonly satisfiedCriteria?: readonly string[];
+}
+export type ItemStateView = 'ready' | 'in-progress' | 'done' | 'closed' | 'blocked';
+export interface ItemView {
+    readonly id: string;
+    readonly projectId: string;
+    readonly title: string;
+    readonly state: ItemStateView;
+    /** The goal that currently owns this work, or null when the queue does. */
+    readonly goalId: string | null;
+    /** Where in the repository the work is, as project-relative paths. */
+    readonly evidence: readonly EvidenceRefView[];
+}
+export interface EvidenceRefView {
+    /** Project-relative. Never absolute — see `ProjectView`. */
+    readonly path: string;
+    readonly line?: number;
+}
+/**
+ * WHAT LOOPLY IS DOING ON A PROJECT RIGHT NOW.
+ *
+ * 🔴 THIS REPLACED A `RunView` THAT WAS PARTLY INVENTED. That interface declared
+ * an `outcome` of `'working' | 'finished' | 'failed' | 'held'`, plus an `id` and
+ * a `goalVersion` — none of which this route has ever sent. It was written from
+ * what a client would find convenient rather than from what the server returns,
+ * and it type-checked perfectly, because a cast cannot be wrong about a shape it
+ * is asserting. `sdk-flagship.e2e.spec.ts` now enumerates every field below
+ * against a live response, with a positive control asserting `outcome` is NOT
+ * among them.
+ *
+ * ⚠️ SO THERE IS NO SINGLE "OUTCOME" FIELD, AND A CLIENT MUST COMPOSE ONE. The
+ * server reports `live`, and `stopReason` once a run has ended. Deriving a
+ * tidier verdict here would mean this SDK asserting a judgement the server never
+ * made — which is the failure the whole package is built to avoid.
+ *
+ * ⚠️ IT IS A WHITELIST OF A LARGER PROJECTION. The internal `Status` also
+ * carries per-round gate steps, item titles, open questions and alerts. Those
+ * are the app's working surface and are omitted deliberately: they change with
+ * the product's needs, and a client pinned to them would be pinned to the
+ * app's release cycle.
+ */
+export interface RunStatusView {
+    readonly projectId: string | null;
+    /** Null when nothing has ever run here. */
+    readonly runId: string | null;
+    readonly lane: string | null;
+    readonly branch: string | null;
+    /**
+     * 🔴 A PAUSED RUN IS STILL `live`. Its process is alive and its budget is
+     * still running down, so this cannot be used alone to decide whether to offer
+     * Pause or Resume.
+     */
+    readonly live: boolean;
+    readonly startedAt: string | null;
+    readonly endedAt: string | null;
+    /** Why the run stopped, in the machine's own words. Null while it runs. */
+    readonly stopReason: string | null;
+    /** The last event folded into this projection. */
+    readonly lastSeq: number;
+    readonly lastEventAt: string | null;
+}
+export type ApprovalStateView = 'pending' | 'approved' | 'denied' | 'expired' | 'revoked';
+export interface ApprovalView {
+    readonly id: string;
+    readonly projectId: string;
+    /** The caller's key for the creation attempt. Request identity, not action identity. */
+    readonly clientRef: string;
+    readonly state: ApprovalStateView;
+    /**
+     * THE EXACT ACTION, IN THE SERVER'S OWN FLAT SHAPE.
+     *
+     * 🔴 AN EARLIER VERSION OF THIS INTERFACE NESTED THESE UNDER `action` as
+     * `{ type, risk, summary }`. The server has never sent that. It sends
+     * `actionType`, `riskClass`, `display` and `action` side by side, and the
+     * flagship caught the difference by reading a real response — a mocked
+     * `fetch` would have handed back the nested shape this file asked for.
+     */
+    readonly actionType: string;
+    /** The digest the approval is bound to. What was approved is what is executed. */
+    readonly actionFingerprint: string;
+    readonly riskClass: string;
+    /** The action rendered for a person to read. This is what a UI should show. */
+    readonly display: string;
+    /**
+     * The canonical parsed action the fingerprint covers.
+     *
+     * ⚠️ ITS FIELDS VARY BY `actionType` AND ARE NOT PROMISED ONE BY ONE. Branch
+     * on `actionType` first. Typed loosely on purpose: pretending to a fixed shape
+     * here would be this SDK asserting a contract the server does not offer.
+     *
+     * ⚠️ NEVER A CREDENTIAL. The broker holds what it needs; anything here reaches
+     * every viewer of the approval screen.
+     */
+    readonly action: Readonly<Record<string, unknown>>;
+    readonly requestedBy: string;
+    readonly requestedAt: string;
+    readonly expiresAt: string;
+    readonly decidedAt: string | null;
+    readonly decidedBy: string | null;
+    readonly decisionNote: string | null;
+    readonly revokedAt: string | null;
+    readonly revokedBy: string | null;
+    /** Optimistic-concurrency token. Deciding against a stale one is a conflict. */
+    readonly version: number;
+    /**
+     * ADVICE, NEVER AUTHORITY: the latest recommendation attached while pending.
+     * `by` is `integration:<id>` or `human:<id>`. Writing it never moves `version`.
+     */
+    readonly recommendation: {
+        readonly decision: 'approve' | 'deny';
+        readonly note: string | null;
+        readonly by: string;
+        readonly at: string;
+    } | null;
+}
+export type ExecutionStateView = 'claimed' | 'executing' | 'result-pending' | 'succeeded' | 'failed'
+/**
+ * 🔴 THE STATE THAT EXISTS BECAUSE THE OUTSIDE WORLD CAN BE UNCLEAR.
+ *
+ * Looply attempted something consequential and cannot establish whether it
+ * happened. It will NOT retry: a client rendering this must not offer one,
+ * and must offer a person the resolution instead.
+ */
+ | 'ambiguous';
+export interface GovernedExecutionView {
+    readonly id: string;
+    readonly projectId: string;
+    readonly approvalId: string;
+    readonly state: ExecutionStateView;
+    readonly startedAt: string;
+    readonly settledAt: string | null;
+    /** Safe, redacted, and never raw command output. */
+    readonly detail: string | null;
+}
+/**
+ * ONE ACT OF PERMISSION TO PURSUE A GOAL AUTONOMOUSLY, AND WHAT BECAME OF IT.
+ *
+ * 🔴 THIS REPLACED AN INVENTED `SafetyView`. That interface had a `holding`
+ * field carrying reasons like `no_progress` and `oscillation` — which are
+ * Phase 9's LOOP-SAFETY reasons, enforced on the machine in
+ * `loop-safety-store.ts` and, as this SDK's own documentation said two
+ * paragraphs earlier, never sent to the server. It described a route that does
+ * not exist using vocabulary that never travels. Both halves were wrong and
+ * neither was catchable by a type.
+ *
+ * What the server actually knows is that a person authorised pursuit, of which
+ * goal at which version, how many Starts it was worth, and — once it is over —
+ * why it ended.
+ */
+export type GoalAutonomyStateView = string;
+export interface GoalAutonomyView {
+    readonly controllerId: string;
+    readonly goalId: string;
+    /**
+     * 🔴 VERSION-SCOPED, AND THAT IS A SAFETY PROPERTY. Permission to pursue
+     * wording 4 is not permission to pursue wording 5 — otherwise editing a goal
+     * would silently re-authorise a machine against text nobody looked at.
+     */
+    readonly goalVersion: number;
+    /**
+     * Which act of permission this was within the version. A version can have
+     * several, and only the newest can still be cancelled — so two rows for one
+     * version are indistinguishable without this.
+     */
+    readonly generation: number;
+    readonly state: GoalAutonomyStateView;
+    /** Why it ended, in the words a person reads. Null while it is still running. */
+    readonly reason: string | null;
+    /** How many Starts this grant was worth. The budget, not a suggestion. */
+    readonly maxStarts: number;
+    readonly expiresAt: string;
+    readonly version: number;
+    readonly createdBy: string;
+    readonly createdAt: string;
+}
+/**
+ * The pursuits of a goal, beside the goal as it stands.
+ *
+ * ⚠️ THE TWO ARRIVE TOGETHER ON PURPOSE. A caller deciding whether to spend
+ * another Start needs both, and reading them separately means acting on two
+ * answers from two moments with an edit able to land in between. The server
+ * returns them in one response for exactly that reason, and this SDK does not
+ * split them back apart.
+ */
+export interface GoalAutonomyReport {
+    readonly autonomy: readonly GoalAutonomyView[];
+    /** Null when the goal does not exist, or is not visible to this caller. */
+    readonly goal: {
+        readonly version: number;
+        readonly state: GoalStateView;
+    } | null;
+}
+/** One gate step as the round's gate recorded it. No output: only the verdict and timing. */
+export interface EvidenceGateStepView {
+    readonly step: string;
+    readonly ok: boolean;
+    readonly ms: number | null;
+    readonly skipped: boolean;
+    readonly timedOut: boolean;
+}
+export interface EvidenceRoundView {
+    readonly seq: number;
+    readonly itemId: string | null;
+    readonly itemTitle: string | null;
+    readonly attempt: number;
+    /** committed | discarded | abandoned, or null while the round is open. */
+    readonly outcome: string | null;
+    readonly sha: string | null;
+    readonly gate: {
+        readonly verdict: string;
+        readonly steps: readonly EvidenceGateStepView[];
+    } | null;
+    /** The prover's verdict and confidence — never its prose, which is a model's sentence about the code. */
+    readonly proof: {
+        readonly verdict: string;
+        readonly confidence: number | null;
+    } | null;
+    /** A person's review of the committed sha: approve | undo, or null. */
+    readonly review: string | null;
+}
+export interface EvidenceRunView {
+    readonly runId: string;
+    readonly branch: string;
+    readonly startedAt: string;
+    readonly endedAt: string | null;
+    readonly stopReason: string | null;
+    readonly rounds: readonly EvidenceRoundView[];
+}
+export interface EvidencePursuitView {
+    readonly controllerId: string;
+    readonly generation: number;
+    readonly state: GoalAutonomyStateView;
+    readonly reason: string | null;
+    readonly maxStarts: number;
+    readonly expiresAt: string;
+    readonly updatedAt: string;
+}
+/** A push carried out under an approval. The sha is the one read back from the remote when known. */
+export interface EvidencePushView {
+    readonly approvalId: string;
+    /**
+     * The server's own approval state — requested | approved | denied | revoked |
+     * expired | claimed — NOT `ApprovalStateView`, which is a mapped vocabulary.
+     * A push happens only after `claimed`.
+     */
+    readonly approvalState: string;
+    /** The governed execution's server state, or null when nothing was attempted. */
+    readonly executionState: string | null;
+    readonly ref: string | null;
+    readonly sha: string | null;
+    readonly settledAt: string | null;
+}
+export interface GoalVersionEvidenceView {
+    readonly goalVersion: number;
+    readonly pursuits: readonly EvidencePursuitView[];
+    readonly runs: readonly EvidenceRunView[];
+    readonly pushes: readonly EvidencePushView[];
+    /** Shas committed under this version. A convenience over `runs`. */
+    readonly landed: readonly string[];
+}
+/**
+ * WHAT THE SERVER SAW OF A GOAL BEING DELIVERED — NOT THE MACHINE'S PROOF.
+ *
+ * Newest version first; a version appears only if something happened under it.
+ * `Round` line counts are absent rather than null: nothing has ever filled
+ * them, and a null would read as "nothing changed".
+ */
+export interface GoalEvidenceView {
+    readonly goal: {
+        readonly id: string;
+        readonly version: number;
+        readonly state: GoalStateView;
+    };
+    readonly versions: readonly GoalVersionEvidenceView[];
+}
+/**
+ * ONE NORMALISED EVENT, ACROSS EVERY INTERNAL LEDGER.
+ *
+ * 🔴 THE INTERNAL STORES STAY SEPARATE. Run events, approval events and
+ * execution events answer different questions, have different authorities and
+ * are written by different components — merging them internally would be a
+ * regression. This is a PROJECTION for clients, and the projection is what has
+ * a single cursor.
+ */
+export interface PlatformEventView {
+    readonly id: string;
+    /**
+     * Opaque, monotonic within a project, and the ONLY thing a client should
+     * persist to resume.
+     *
+     * ⚠️ NOT A TIMESTAMP AND NOT AN INTEGER TO DO ARITHMETIC ON. It is compared
+     * for equality and passed back verbatim; anything else assumes a structure
+     * the server has not promised.
+     */
+    readonly cursor: string;
+    readonly projectId: string;
+    readonly type: string;
+    readonly occurredAt: string;
+    readonly resourceType: 'goal' | 'item' | 'run' | 'approval' | 'execution' | 'project';
+    readonly resourceId: string;
+    /** Safe, whitelisted, and never raw output or a credential. */
+    readonly payload: Readonly<Record<string, unknown>>;
+}
+/**
+ * ⚠️ THERE IS NO `EvidenceView`, AND THE ONE THAT WAS HERE HAS BEEN REMOVED.
+ *
+ * It declared `{ id, projectId, runId, kind, at, summary }` for a `/evidence`
+ * route that does not exist. An exported type with no method producing it is the
+ * same defect as a method with no route behind it: a promise the package cannot
+ * keep, and one a caller will write code against.
+ *
+ * Gate results, verifier verdicts and failure signatures ride the RUN EVENT
+ * LEDGER. Read `events()` and filter by `type`.
+ */
+/**
+ * WHAT BECAME OF ONE INSTRUCTION.
+ *
+ * 🔴 THERE ARE EXACTLY TWO STATES AND THERE IS DELIBERATELY NO MIDDLE ONE.
+ * "The machine has it" is not a state a client may branch on: a command is
+ * either still deliverable or it is finished, and inventing "in progress" would
+ * invite a client to render a spinner it can never clear — the daemon does not
+ * report picking something up, only acking it.
+ *
+ * ⚠️ `done` ON A START MEANS THE START WAS ACCEPTED, NOT THAT THE WORK
+ * SUCCEEDED. Composing this with `status()` is how a client learns the rest.
+ */
+export interface CommandStatusView {
+    readonly id: string;
+    /** Which instruction this was — `start-run`, `pause`, `stop`, and so on. */
+    readonly kind: string;
+    readonly state: 'pending' | 'terminal';
+    /**
+     * ⚠️ ABSENT, NOT NULL, WHILE PENDING — and the difference is not cosmetic.
+     *
+     * The server OMITS these keys rather than sending null, so a client writing
+     * `if (s.outcome === null)` would be comparing against `undefined` and taking
+     * the wrong branch. Written down as optional because that is what arrives on
+     * the wire; an earlier version of this interface declared them nullable and
+     * named the timestamp `settledAt`, which the server has never sent.
+     *
+     * `expired` is written by no ack — it is inferred from the delivery window.
+     */
+    readonly outcome?: 'done' | 'refused' | 'expired';
+    /** Why it was refused, so a client can say more than "no". */
+    readonly reason?: string;
+    readonly issuedAt: string;
+    /** When the daemon acked it. Absent while pending. */
+    readonly ackedAt?: string;
+    /**
+     * When it stops being deliverable: the `deliverBy` the caller gave, or the
+     * default one-hour window. Null for a kind that never expires.
+     */
+    readonly deliverBy: string | null;
+    /**
+     * Pending and past its deadline. Expiry is written when the machine next
+     * polls, so a command for a sleeping machine reads `pending` until it wakes;
+     * this is what says that `pending` is no longer a promise.
+     */
+    readonly overdue: boolean;
+}
+/**
+ * Whether the machine that holds a project is awake. Online is a live
+ * heartbeat; `lastOnline` is when it was last heard from.
+ */
+export interface PresenceView {
+    readonly machineId: string;
+    readonly online: boolean;
+    readonly lastOnline: string | null;
+    readonly cliVersion: string | null;
+}
+/**
+ * Every list answer, so no route can quietly return everything.
+ *
+ * `nextCursor === null` means the end; it does NOT mean "ask again later".
+ */
+export interface PageView<T> {
+    readonly items: readonly T[];
+    readonly nextCursor: string | null;
+}
+/** One ledger line an answer rests on, so a reader can check it. */
+export interface KeeperCitationView {
+    readonly runId: string;
+    readonly seq: number;
+    readonly kind: string;
+    readonly at: string;
+}
+/**
+ * What the keeper said, and what it read to say it (DESIGN §9 read path).
+ *
+ * ⚠️ `kind` IS THE ASK IT UNDERSTOOD, NOT A TOPIC LABEL. `unknown` means the
+ * question was not recognised and `text` is the keeper saying so — a client that
+ * renders `unknown` as an answer presents a refusal as a reply.
+ *
+ * Every sentence in `text` is composed from `citations` and nothing else; the
+ * read path runs no model. A client that wants to show its working has the seqs
+ * to resolve through `events()`.
+ */
+export interface KeeperAnswerView {
+    readonly question: string;
+    readonly kind: 'working-on' | 'needs-me' | 'time-left' | 'failures' | 'landed' | 'safety' | 'unknown';
+    readonly text: string;
+    readonly citations: readonly KeeperCitationView[];
+    /** True when more lines were read than are cited — the list is bounded. */
+    readonly citationsTruncated?: boolean;
+}
+/**
+ * A document a person handed over — a plan, a spec — kept exactly as handed
+ * over and content-addressed. A `pdf` arrives as the pages of its text layer,
+ * read on the machine that holds the file; a scanned PDF is refused there
+ * rather than accepted and silently emptied.
+ */
+export type SourceKindView = 'markdown' | 'text' | 'pdf';
+/** What a statement IS structurally. Never what it means. */
+export type SourceStatementKindView = 'heading' | 'paragraph' | 'list-item' | 'table' | 'code' | 'unsupported';
+export interface SourceStatementView {
+    /** 1-based position in document order. */
+    readonly ordinal: number;
+    readonly kind: SourceStatementKindView;
+    /** The statement's lines, verbatim, joined with a newline. */
+    readonly text: string;
+    readonly anchor: {
+        /** For a pdf: the 1-based page the lines are on. Absent for text kinds. */
+        readonly page?: number;
+        /** 1-based, inclusive, counted in the document as stored. */
+        readonly lineStart: number;
+        readonly lineEnd: number;
+        /** The enclosing heading chain, outermost first. Empty for plain text. */
+        readonly headingPath: readonly string[];
+    };
+}
+/** A source as a list answers with it: identity and provenance, no content. */
+export interface SourceView {
+    readonly id: string;
+    readonly projectId: string;
+    /** The name the caller gave it — typically the file name. Not unique. */
+    readonly name: string;
+    readonly kind: SourceKindView;
+    /** Hex sha256 of the UTF-8 bytes of the content. The identity of the source. */
+    readonly sha256: string;
+    /** For a pdf: the sha256 of the file the text was read from, as the reader reported. Provenance, not authority. */
+    readonly originSha256?: string;
+    readonly byteLength: number;
+    /** The caller's own key for the creation attempt. See `createSource`. */
+    readonly clientRef: string;
+    readonly createdAt: string;
+}
+/** The stored record as the wire carries it: the summary plus the verbatim content. */
+export interface SourceRecordView extends SourceView {
+    readonly content: string;
+}
+/** What a statement IS to a plan. Never what the repository has done about it. */
+export type StatementClassView = 'requirement' | 'constraint' | 'context' | 'duplicate' | 'exclusion' | 'question';
+export interface SourceClassificationView {
+    /** The statement's ordinal within its source. */
+    readonly ordinal: number;
+    readonly class: StatementClassView;
+    /** For a requirement: demands (`positive`) or forbids (`negative`). */
+    readonly polarity?: 'positive' | 'negative';
+    /** For a duplicate: the ordinal it repeats. */
+    readonly duplicateOf?: number;
+    /** The rule that decided, so a reader can argue with it. */
+    readonly rule: string;
+    readonly classifierVersion: number;
+}
+/**
+ * Where a requirement stands against the repository, as MEASURED on the
+ * machine at a tree. `absent` names nothing; `candidate` is a place to look
+ * (anchors), not evidence; `conflicting` contradicts another statement of the
+ * same source; `blocked` could not be measured (no index, no terms, only
+ * unparsed files). `implemented-and-evidenced` and `partial` are what a person
+ * says with evidence — no rule produces them, and the reconcile route refuses
+ * them.
+ */
+export type DispositionKindView = 'absent' | 'candidate' | 'conflicting' | 'blocked' | 'implemented-and-evidenced' | 'partial';
+/** One place in the repository that names a statement's terms. */
+export interface RepositoryAnchorView {
+    /** Canonical repository path, as the project index records it. */
+    readonly path: string;
+    /** The line of the first symbol there that names a term; absent when only the path did. */
+    readonly line?: number;
+    /** Which of the statement's terms this place names. */
+    readonly terms: readonly string[];
+}
+export interface SourceDispositionView {
+    /** The statement's ordinal within its source. */
+    readonly ordinal: number;
+    readonly disposition: DispositionKindView;
+    /** The statement's terms — what was looked for. */
+    readonly terms: readonly string[];
+    /** Best first, capped; `candidatesTotal` says how many there were before the cap. */
+    readonly anchors: readonly RepositoryAnchorView[];
+    readonly candidatesTotal: number;
+    /** For `conflicting`: the ordinal that contradicts this one. */
+    readonly conflictsWith?: number;
+    /** The rule that decided. */
+    readonly rule: string;
+    readonly reconcilerVersion: number;
+}
+/** One place a person points at as evidence. */
+export interface EvidenceAnchorView {
+    readonly path: string;
+    readonly line?: number;
+    /** The words at that place, as the person read them. At most 300 characters. */
+    readonly quote?: string;
+}
+/**
+ * What a PERSON said about a requirement, with evidence, at a tree — the only
+ * way `implemented-and-evidenced` or `partial` reaches a source. Never written
+ * by a machine token or by a rule.
+ */
+export interface SourceAttestationView {
+    readonly ordinal: number;
+    readonly disposition: 'implemented-and-evidenced' | 'partial';
+    /** The committed tree the evidence was read at. */
+    readonly treeSha: string;
+    /** At least one; at most 8. */
+    readonly anchors: readonly EvidenceAnchorView[];
+    readonly note?: string;
+    /** `human:<deviceId>`, from the token that made the request. */
+    readonly attestedBy: string;
+    readonly createdAt: string;
+}
+/** One source, verbatim, with its anchored statements, the latest classification of each, the most recent reconciliation, and what people attested. */
+export interface SourceDetailView extends SourceRecordView {
+    readonly statements: readonly SourceStatementView[];
+    readonly classifications: readonly SourceClassificationView[];
+    /** The classifier version the classifications came from; null when none were ever made. */
+    readonly classifierVersion: number | null;
+    /** The most recent hand-over of where each requirement stands; empty when none was ever made. */
+    readonly dispositions: readonly SourceDispositionView[];
+    /** The tree and reconciler version those dispositions were measured at; null when there are none. */
+    readonly reconciledAt: {
+        readonly treeSha: string;
+        readonly reconcilerVersion: number;
+        readonly createdAt: string;
+    } | null;
+    /** The latest attestation per statement; empty when nobody said anything. */
+    readonly attestations: readonly SourceAttestationView[];
+}
+/**
+ * One word per requirement: `unserved` (no goal names it), `served` (a goal
+ * names it), `partial` / `evidenced` (a person's word at the tree of the
+ * latest measurement), `evidenced-at-an-earlier-tree`. Nothing here comes
+ * from a rule or from a finished queue.
+ */
+export type CoverageKindView = 'unserved' | 'served' | 'partial' | 'evidenced' | 'evidenced-at-an-earlier-tree';
+export interface GoalRefView {
+    readonly id: string;
+    readonly state: string;
+    readonly version: number;
+}
+export interface RequirementCoverageView {
+    readonly ordinal: number;
+    readonly class: 'requirement' | 'constraint';
+    /**
+     * Whether this one can block a COMPLETE, or is only a recommendation.
+     *
+     * ⚠️ NAMED HERE OR THE APP NEVER SEES IT. This view is an ingress
+     * allow-list: a field the server sends and this interface does not declare is
+     * dropped without a word and without a type error, so the phone would render
+     * the same "everything is a MUST" the CLI did.
+     */
+    readonly mandatory: boolean;
+    /** Whether the document said "must NOT" rather than "must". Named for the same reason. */
+    readonly negative: boolean;
+    /** The statement's first line. */
+    readonly text: string;
+    readonly anchor: SourceStatementView['anchor'];
+    readonly goals: readonly GoalRefView[];
+    readonly disposition?: SourceDispositionView;
+    readonly attestation?: SourceAttestationView;
+    readonly coverage: CoverageKindView;
+}
+/** What is covered and by whom, for one source. */
+/**
+ * A person's authorization to direct one session, as the server holds it (F-14).
+ *
+ * ⚠️ READ-ONLY TO EVERY CLIENT. The fields that decide authority — who issued
+ * it, the handshake nonce, the expiry, the state — are stamped by the server and
+ * appear here only so a machine can ASK whether it may act. Nothing a client
+ * sends can set them.
+ */
+export interface SessionControlGrantView {
+    readonly id: string;
+    /** `human:<deviceId>`. A grant whose issuer is a machine authorizes nothing. */
+    readonly issuedBy: string;
+    readonly projectId: string;
+    readonly sessionId: string;
+    readonly repositoryId: string;
+    readonly workspace: string;
+    readonly scope: readonly string[];
+    readonly handshakeNonce: string;
+    readonly issuedAt: string;
+    readonly expiresAt: string;
+    readonly state: 'authorized' | 'revoked' | 'expired';
+    readonly generation: number;
+    /** The optimistic-concurrency token the revoke route demands; see core's note. */
+    readonly version: number;
+}
+export interface SourceCoverageView {
+    readonly sourceId: string;
+    readonly name: string;
+    readonly reconciledAt: SourceDetailView['reconciledAt'];
+    readonly requirements: readonly RequirementCoverageView[];
+    readonly tally: Readonly<Record<CoverageKindView, number>>;
+}
+//# sourceMappingURL=views.d.ts.map