@opencode-cockpit/trust 0.0.0 → 0.8.0

package/types/core/danger.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Which commands cost more trust.
+ *
+ * Nothing here blocks anything. A dangerous command still earns trust like any other; it needs the
+ * normal threshold *plus* `dangerExtra` approvals in a row (docs/roadmap/trust.md, "Decided"). So a
+ * miss in this list is never a hole — the command still had to be approved `threshold` times — it is
+ * only a command that became automatic sooner than it should have. A false alarm costs a few more
+ * approvals and nothing else, which is why every doubt below is settled towards "dangerous".
+ *
+ * It sees one command at a time: `git add -A && git push --force` arrives as two, and only the second
+ * is dangerous. `cwd` is already part of the signature; this is about what the words do.
+ *
+ * The answer is a reason rather than a yes, because the ledger shows it: "git push" says why a rule
+ * needs eight approvals where `true` would leave the person guessing.
+ */
+import type { Command } from "./shell.ts";
+/**
+ * Wrappers run the command after them, so the wrapped command is the one judged. Each lists the
+ * flags that take a separate value, so `timeout -s KILL 5 rm x` finds `rm` rather than `KILL`.
+ * `sudo` and `doas` are dangerous in themselves: whatever runs, runs as root.
+ */
+export interface Wrapper {
+    /** Flags whose value is the next word. */
+    values?: readonly string[];
+    /** Positional words the wrapper takes before the command: `timeout 5`, `nice` has none. */
+    positionals?: number;
+    /** Running as someone else is dangerous whatever the command is. */
+    dangerous?: string;
+}
+export declare const WRAPPERS: Readonly<Record<string, Wrapper>>;
+export declare const COMPOSE_GLOBALS: string[];
+/**
+ * The flags before a tool's subcommand that take a separate value, by program: what family.ts needs
+ * to find `status` in `git -C /x status`. Read from the table above so the two cannot disagree.
+ */
+export declare const TOOL_GLOBALS: Readonly<Record<string, readonly string[]>>;
+/** The words after the global flags: `[-C, /tmp, push, origin]` → `[push, origin]`. */
+export declare function subcommand(args: readonly string[], globals?: readonly string[]): string[];
+/**
+ * One wrapper taken off the front: its name, and the words it runs. Undefined when `argv` does not
+ * start with a wrapper. Families (family.ts) keep the wrapper's name — `sudo ls` is not `ls` — and
+ * drop its flags, so this is shared rather than copied.
+ */
+export declare function unwrapOnce(argv: readonly string[]): {
+    wrapper: string;
+    rest: readonly string[];
+} | undefined;
+/** Why a command costs more trust, in a few words — or nothing when it costs the usual. */
+export declare function dangerOf(command: Command): string | undefined;
+export declare function dangerous(command: Command): boolean;

package/types/core/engine.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Trust in one window: the requests it is watching, the replies it sent, and the events each turn
+ * of that produces. No clock, no file, no OpenCode — times are passed in, events are handed back to
+ * be written, and the file's events (this window's and every other's) come back in through `load`.
+ *
+ * That last loop is deliberate. An event this window writes is applied when it is read back from the
+ * file, in the file's order, exactly like another window's: the state is one fold over one sequence,
+ * never a fold of "ours" patched with "theirs".
+ *
+ * **Who answered.** `permission.replied` does not say (docs/opencode/permissions.md), so:
+ * our own replies are known by request id; a reply under `PERSON_MS` after the request is not a
+ * person — OpenCode's `--auto` answers in 15–22ms, a person in a second or more — and is not counted;
+ * a request asked before this window was watching has no time to measure, and is not counted either.
+ * Every doubt under-counts a person, never over-counts one. A reject always counts: resetting is the
+ * safe direction.
+ */
+import { type History } from "./history.ts";
+import type { Context, Request } from "./keys.ts";
+import { type Event, type State, type Thresholds } from "./ledger.ts";
+import { type Judgement } from "./policy.ts";
+import type { ConfigRule } from "./rules.ts";
+/** Faster than this, nobody read the prompt. Measured: auto mode 15–22ms, a person 1.2s and up. */
+export declare const PERSON_MS = 300;
+/** How long a request must have been pending before the host's list may say it is gone. */
+export declare const RECONCILE_AFTER_MS = 10000;
+export type Reply = "once" | "always" | "reject";
+export type Credit = {
+    kind: "approved";
+    always?: string[];
+} | {
+    kind: "rejected";
+} | {
+    kind: "ignored";
+    why: string;
+};
+/** Whose reply this was, as far as can be known — and so what it counts for. */
+export declare function credit(input: {
+    reply: Reply;
+    /** When the request was asked; undefined when this window never saw it asked. */
+    askedAt?: number;
+    repliedAt: number;
+    /** This window answered it. */
+    ours: boolean;
+    always?: string[];
+}): Credit;
+export interface Pending {
+    request: Request;
+    agent: string;
+    askedAt: number;
+    judgement: Judgement;
+}
+/** One answer Trust gave, for the sidebar's list. */
+export interface Answered {
+    at: number;
+    request: string;
+    permission: string;
+    agent: string;
+    /** The subjects, as one line: `git status`, or `git add -A && git commit -m wip`. */
+    label: string;
+    subjects: string[];
+    why: string;
+    /** The widened family that answered it, when one did: the sidebar says "any ls". */
+    via?: string;
+}
+export interface EngineOptions extends Thresholds {
+    /** Answers by Trust kept for the sidebar. */
+    keep?: number;
+}
+export interface Engine {
+    readonly state: State;
+    /**
+     * When things happened, for the screens that say why (history.ts): folded from the same events as
+     * the state, bounded, and never read by a decision.
+     */
+    readonly history: History;
+    /** Events read from the ledger file, in file order. */
+    load(events: readonly Event[], options?: {
+        reset?: boolean;
+    }): void;
+    /**
+     * A request was asked. Returns the judgement and the `asked` event to write; when the judgement is
+     * to answer, the request is marked ours *before* the reply is sent, so the `replied` it causes is
+     * never mistaken for a person's.
+     */
+    ask(input: {
+        request: Request;
+        context: Context;
+        agent: string;
+        rules: readonly ConfigRule[];
+        at: number;
+    }): {
+        judgement: Judgement;
+        event: Event;
+    };
+    /** Our reply went through: the `auto` event to write. */
+    answered(requestID: string, at: number): Event | undefined;
+    /** Our reply failed: the request is the person's again, and their answer counts. */
+    failed(requestID: string): void;
+    /** A reply arrived — ours, OpenCode's, a person's. The events to write, and what it was taken for. */
+    replied(input: {
+        requestID: string;
+        reply: Reply;
+        at: number;
+    }): {
+        events: Event[];
+        credit: Credit;
+    };
+    /** Requests the host says are no longer pending: answered while we were not looking. */
+    reconcile(stillPending: ReadonlySet<string>, now: number): void;
+    pending(): Pending[];
+    /** Trust's answers in this window, newest first. */
+    recent(): Answered[];
+    /** How many answers Trust gave in this window. */
+    count(): number;
+    reset(options: EngineOptions): void;
+}
+export declare function createEngine(initial: EngineOptions): Engine;

package/types/core/family.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Families: what several exact rules have in common, and how a rule is shown so nothing about it is
+ * left to the font.
+ *
+ * A signature is exact on purpose (signature.ts), so a project that runs `ls -la`, `ls -la src` and
+ * `ls -R docs` has three rules — which is right for trust and wrong for reading: a ledger of forty
+ * exact lines does not say "you trust ls". A family is the part of a command that names *what it
+ * does*: the program, and for a tool with subcommands, the subcommand (`git status`, `docker compose
+ * up`, `npm run test`). The ledger groups by it, and it is the one unit a person can widen trust to,
+ * on purpose (`w` in the ledger) — never Trust by itself (docs/roadmap/trust.md).
+ *
+ * The rules, and why each one leans the way it does:
+ *
+ * - **Global flags are not part of the family**: `git -C /x status` is `git status`, and
+ *   `docker compose -p prod down -v` is `docker compose down` — the flags change *where*, the
+ *   subcommand says *what*. Read with danger.ts's own tables, so the two never disagree on where the
+ *   subcommand is.
+ * - **A wrapper is part of it**: `sudo ls` is not `ls`, and neither is `timeout 5 ls`. Trusting any
+ *   `ls` must not quietly cover running it as root.
+ * - **So is where it runs and what it is told**: `(in web) bun test` and `NODE_ENV=… npm run build`
+ *   are their own families. A directory or an environment changes what the same words do.
+ * - **Redirections are not**: `ls > out.txt` groups under `ls` — but a widened family does not cover
+ *   it (`outside`), because writing a file is not what "any ls" was agreed to mean.
+ *
+ * Other permissions: an edit's family is its folder (`src/`), a fetch's its host, an agent type is
+ * its own — the last two already are as wide as they go.
+ */
+import { type Command } from "./shell.ts";
+/**
+ * A bash subject read back into its command. A signature is written to be parsed again — every word
+ * quoted by `quote` — so this is exact; anything that does not read as one command is left alone.
+ */
+export declare function readSubject(subject: string): {
+    place?: string;
+    command: Command;
+} | undefined;
+export declare const isRedirect: (word: string) => boolean;
+/**
+ * A subject's family, under its permission. The same string for every command in it, so it is what
+ * a widening is recorded against and what the ledger groups by.
+ */
+export declare function familyOf(permission: string, subject: string): string;
+/**
+ * Whether a family may be widened at all. A dangerous family never: if `git push` itself is
+ * dangerous, "any git push" is a rule that answers force-pushes — every one of them has to earn
+ * trust on its own, at the higher count. A fetch or an agent type is already as wide as it goes.
+ */
+export declare function widenable(permission: string, family: string): {
+    ok: true;
+} | {
+    ok: false;
+    why: string;
+};
+/**
+ * Why a widened family would still ask about this subject — or nothing when it covers it. A widening
+ * is "any `ls`", not "anything that starts with ls": a dangerous command, one that writes a file
+ * through a redirection, and one that hands its arguments to another program each still ask.
+ */
+export declare function outside(permission: string, subject: string): string | undefined;
+/** A widened `family` answers `subject`. */
+export declare const covers: (permission: string, family: string, subject: string) => boolean;
+/**
+ * One word as the ledger shows it: bare when nothing about it can be misread, otherwise in double
+ * quotes — easier to read than the signature's single quotes, and this is display, never parsed.
+ * A punctuation-only word is always quoted (a lone `-` or `.` aside: one character cannot merge).
+ */
+export declare function shown(word: string): string;
+/**
+ * The runs of a word a font may draw as one glyph, said in words: `---` is "3 hyphens", `->` is
+ * "hyphen, greater-than". Quotes were not enough — inside them `"---"` still drew as `"──"` on the
+ * user's screen — so the ledger says it in letters, which no font merges.
+ */
+export declare function spelled(word: string): string | undefined;
+/**
+ * Each argument of a subject a font may draw as something else, as the ledger shows it (`"---"`)
+ * beside what it is in words (`3 hyphens`). The panel says which word it means: a bare `3 hyphens`
+ * after a command read as a riddle (a user's screenshot).
+ */
+export declare function spelledWords(permission: string, subject: string): {
+    word: string;
+    said: string;
+}[];
+/** The spelled runs of every argument of a subject, for the ledger to put beside it. */
+export declare function spelledSubject(permission: string, subject: string): string | undefined;
+/** A command as the ledger shows it: every argument unambiguous, redirections as redirections. */
+export declare function showCommand(command: Command): string;
+/** A subject — or a family — as the ledger and the sidebar show it. Paths and hosts are themselves. */
+export declare function showSubject(permission: string, subject: string): string;
+/** `any ls …`, `any file in src/`: what a widened family answers, in words. */
+export declare function anyOf(permission: string, family: string): string;
+/**
+ * A command a little different from `subject`, for the sentence that says what still asks: the
+ * command with its last argument dropped, or nothing when it has none past its family.
+ */
+export declare function narrower(subject: string): string | undefined;
+/** The subject with its output sent to a file: the other thing that still asks. */
+export declare function redirected(subject: string): string | undefined;

package/types/core/history.d.ts

@@ -0,0 +1,81 @@
+/**
+ * What happened, and when — read from the same events the state is folded from, for the screens
+ * that say *why*: what Trust answered today, how the week went, and the approvals that earned a rule.
+ *
+ * The state (ledger.ts) keeps what a rule adds up to — a streak, a count, the last time — because
+ * that is all a decision needs. A person asking "why is this trusted?" needs the moments themselves:
+ * `✓ 9h  ✓ 9h  ✓ 9h → trusted`. So this is a second fold over the same sequence, beside the state and
+ * never consulted by `decide`: nothing here changes what Trust answers.
+ *
+ * Bounded, because a ledger only grows: the last `MARKS` moments per rule (a run of answers is one
+ * moment with a count, so a rule answered a thousand times does not push out the approvals that
+ * earned it), the last `ANSWERS` answers, and a count of answers per day for the last `DAYS` days.
+ * A rule older than its window still has its totals in the state; the screens fall back to those.
+ */
+import type { Event, Item } from "./ledger.ts";
+/** One moment in a rule's life. A run of answers in a row is one mark, `count` of them. */
+export type Mark = {
+    kind: "approved";
+    at: number;
+} | {
+    kind: "rejected";
+    at: number;
+} | {
+    kind: "revoked";
+    at: number;
+} | {
+    kind: "auto";
+    at: number;
+    count: number;
+};
+/** One answer Trust gave, from any window on the project. */
+export interface Answer {
+    at: number;
+    request: string;
+    permission: string;
+    agent: string;
+    items: Item[];
+    /** Why, as the window that answered put it (policy.ts). */
+    rule: string;
+}
+export interface History {
+    /** By `keyOf(permission, agent, subject)`, oldest first. */
+    marks: Map<string, Mark[]>;
+    /** Oldest first, the last `ANSWERS`. */
+    answers: Answer[];
+    /** Answers per local day, by the day's first millisecond. */
+    days: Map<number, number>;
+}
+/** Moments kept per rule. */
+export declare const MARKS = 24;
+/** Answers kept for the activity feed: far more than a screen lists. */
+export declare const ANSWERS = 200;
+/** Days of answers counted: a week, and a week before it to spare. */
+export declare const DAYS = 14;
+export declare const emptyHistory: () => History;
+/** The first millisecond of the local day `at` falls in. */
+export declare function dayOf(at: number): number;
+/**
+ * One event into the history. `settled` is the state's set of requests already counted, read before
+ * the state applies this event: two windows writing one outcome are one moment here as there.
+ */
+export declare function note(history: History, event: Event, settled: ReadonlySet<string>): void;
+/** Answers newest first. */
+export declare const latestAnswers: (history: History, limit?: number) => Answer[];
+/** Answers on each of the last `days` local days, the oldest first and today last. */
+export declare function answersPerDay(history: History, now: number, days?: number): number[];
+/** How a rule came to be trusted, read back from its moments. */
+export interface Earned {
+    /** Approvals in a row that count, as of `upTo`. */
+    streak: number;
+    /** When the streak reached what it needed; undefined when it has not (or the window lost it). */
+    since?: number;
+    /** The streak was broken by a reject or a revoke before it began: when. */
+    brokenAt?: number;
+    broken?: "rejected" | "revoked" | "expired";
+}
+/**
+ * The streak a rule's moments add up to, the way the state folds it (a reject or revoke starts it
+ * over, an approval after `expireMs` unused starts it over) — and when it reached `need`.
+ */
+export declare function earned(marks: readonly Mark[], need: number, expireMs: number, upTo?: number): Earned;

package/types/core/index.d.ts

@@ -0,0 +1,16 @@
+/** Published entry point: `@opencode-cockpit/trust/core` — the pure half, no OpenCode, no terminal. */
+export { commandOf, type Seen } from "./adapt/seen.ts";
+export { fromV1Event, fromV1Pending, V1_EVENTS } from "./adapt/v1.ts";
+export { fromV2Event, fromV2Pending } from "./adapt/v2.ts";
+export * from "./config.ts";
+export { dangerOf, dangerous } from "./danger.ts";
+export * from "./engine.ts";
+export { anyOf, covers, familyOf, outside, shown, showSubject, widenable } from "./family.ts";
+export { type Answer, answersPerDay, earned, type History, latestAnswers, type Mark } from "./history.ts";
+export * from "./keys.ts";
+export * from "./ledger.ts";
+export * from "./paths.ts";
+export * from "./policy.ts";
+export * from "./rules.ts";
+export { type Command, type Parsed, parse } from "./shell.ts";
+export { place, quote, signature } from "./signature.ts";

package/types/core/keys.d.ts

@@ -0,0 +1,68 @@
+/**
+ * What a permission request is a request *for*, as the things an approval can be counted against.
+ *
+ * Each permission type has its own notion of "the same thing again":
+ *
+ * | permission | one subject per | e.g. |
+ * | --- | --- | --- |
+ * | `bash` (v2 `shell`) | command, by its exact signature | `git status`, `(in web) bun test` |
+ * | `edit` | file path | `src/app.ts` |
+ * | `webfetch` | host | `docs.example.com` |
+ * | `task` (v2 `subagent`) | agent type | `explore` |
+ * | `external_directory`, `doom_loop` | — never answered | |
+ * | anything else | the request's patterns, together | `opencode_read_mcp_resource` `*` |
+ *
+ * The key a count is kept under is the subject *and* the permission *and* the agent: trust earned
+ * by `build` running `git push` is not trust for `general` to run it.
+ */
+/** A permission request, whichever OpenCode asked it (see `adapt/`). */
+export interface Request {
+    id: string;
+    sessionID: string;
+    /** Canonical: `bash`, `edit`, `task`… (`rules.canonical`). */
+    permission: string;
+    /** What OpenCode matched against config: v1 `patterns`, v2 `resources`. */
+    patterns: string[];
+    /** What OpenCode's own "always" would approve: v1 `always`, v2 `save`. */
+    always: string[];
+    /** The tool call that asked, so a later surface can mark it answered by Trust. */
+    call?: string;
+    messageID?: string;
+}
+/** Everything about the call that the request itself does not carry. */
+export interface Context {
+    /** The command line as the agent wrote it — a bash request's patterns lose `cd`. */
+    line?: string;
+    /** The tool's own working directory argument (v1 `workdir`, v2 `cwd`). */
+    workdir?: string;
+    /** The project's directory: signatures name places relative to it. */
+    root: string;
+}
+export interface Subject {
+    /** The exact thing counted: a signature, a path, a host… */
+    subject: string;
+    /** What config is matched against for this subject: the command as written, the path, the URL. */
+    texts: string[];
+    /** Why it costs more trust, when it does. */
+    danger?: string;
+}
+export type Keyed = {
+    kind: "subjects";
+    subjects: Subject[];
+    /**
+     * The request's own patterns. They are what OpenCode checked its rules against, so a specific
+     * `ask` matching any of them holds the whole request, even where our reading of it differs.
+     */
+    patterns: string[];
+}
+/** Never answered by Trust, whatever the count. */
+ | {
+    kind: "never";
+    why: string;
+}
+/** Cannot be read for certain, so it is asked — and nothing is counted. */
+ | {
+    kind: "opaque";
+    why: string;
+};
+export declare function subjectsOf(request: Request, context: Context): Keyed;

package/types/core/ledger.d.ts

@@ -0,0 +1,158 @@
+/**
+ * The ledger: what happened, one event per line, and what it adds up to.
+ *
+ * Append-only on purpose. Several OpenCode windows on one project write to the same file, and a
+ * whole line appended in one write is the only update that needs no lock: nothing is ever rewritten,
+ * so no window can undo another's. The state is never stored — it is a fold over the events, so it
+ * cannot drift from them, and a rule's history ("approved 3×, rejected once, approved again") is
+ * there to read rather than summarised away.
+ *
+ * Reading is forgiving in exactly one way: a line cut short by a crash is skipped, and a line written
+ * after it (which then starts mid-line) is recovered. Anything else that does not parse is ignored —
+ * a ledger you edited by hand should cost you a rule, not the bay.
+ */
+export interface Item {
+    subject: string;
+    danger?: string;
+    /** On an answer by Trust: the widened family that answered it, rather than the rule's own count. */
+    via?: string;
+}
+/** What every event about one request carries. */
+interface About {
+    request: string;
+    session: string;
+    /** The tool call that asked: what a later surface needs to mark the call answered by Trust. */
+    call?: string;
+    permission: string;
+    agent: string;
+    items: Item[];
+}
+export type Event = {
+    v: 1;
+    at: number;
+} & (({
+    type: "asked";
+    why?: string;
+} & About)
+/** A person approved it (a reply too fast for a person is never recorded as one). */
+ | ({
+    type: "approved";
+    always?: string[];
+} & About) | ({
+    type: "rejected";
+} & About)
+/** Trust approved it; `rule` says why, in words. */
+ | ({
+    type: "auto";
+    rule: string;
+} & About)
+/** You took a rule's trust away; it has to be earned again. */
+ | {
+    type: "revoked";
+    permission: string;
+    agent: string;
+    subject: string;
+}
+/**
+ * You trusted a whole family (family.ts) for one agent: any command in it is answered, except the
+ * ones a widening never covers. Only a person writes this; Trust never widens by itself.
+ */
+ | {
+    type: "widened";
+    permission: string;
+    agent: string;
+    family: string;
+}
+/** The family is back to its exact rules, each standing on its own count. */
+ | {
+    type: "unwidened";
+    permission: string;
+    agent: string;
+    family: string;
+}
+/** Trust stops answering in this project until resumed — every window, not just this one. */
+ | {
+    type: "paused";
+} | {
+    type: "resumed";
+});
+/** One subject's standing, under one permission and one agent. */
+export interface Entry {
+    key: string;
+    permission: string;
+    agent: string;
+    subject: string;
+    /** Why it costs more, as of the last time it was asked. */
+    danger?: string;
+    /** Approvals by a person in a row since the last reject, revoke or expiry. */
+    streak: number;
+    /** Every approval by a person, ever. */
+    approvals: number;
+    /** Every answer by Trust, ever. */
+    autos: number;
+    firstAt: number;
+    /** Last approved or answered: what expiry counts from. */
+    lastAt: number;
+    rejectedAt?: number;
+    revokedAt?: number;
+}
+/** An "always" a person gave OpenCode itself: broader than it looks, and gone when OpenCode stops. */
+export interface Always {
+    at: number;
+    session: string;
+    permission: string;
+    agent: string;
+    patterns: string[];
+}
+/** A family you trusted as a whole, for one agent under one permission. */
+export interface Widened {
+    key: string;
+    permission: string;
+    agent: string;
+    family: string;
+    at: number;
+}
+export interface State {
+    entries: Map<string, Entry>;
+    /** By `keyOf(permission, agent, family)`: the same key shape as a rule, a different namespace. */
+    widened: Map<string, Widened>;
+    always: Always[];
+    paused: boolean;
+    /** Requests already settled: two windows writing one outcome count it once. */
+    settled: Set<string>;
+}
+export interface FoldOptions {
+    /** Unused this long, trust starts again from nothing. 0 never expires. */
+    expireMs: number;
+}
+export declare const DAY = 86400000;
+export declare const emptyState: () => State;
+export declare const keyOf: (permission: string, agent: string, subject: string) => string;
+export declare function apply(state: State, event: Event, options: FoldOptions): State;
+export declare function applyAll(state: State, events: readonly Event[], options: FoldOptions): State;
+export interface Thresholds {
+    threshold: number;
+    dangerExtra: number;
+    expireDays: number;
+}
+export interface Standing {
+    /** Approvals in a row that still count. */
+    have: number;
+    need: number;
+    trusted: boolean;
+    expired: boolean;
+}
+export declare function needFor(danger: string | undefined, settings: Thresholds): number;
+/** Where a subject stands now. `danger` is today's reading, which wins over the one stored. */
+export declare function standing(found: Entry | undefined, danger: string | undefined, settings: Thresholds, now: number): Standing;
+/**
+ * Events in `text`, and what is left after the last newline. The rest is not an error: it is a line
+ * another window is still writing, read again next time.
+ */
+export declare function parseLines(text: string): {
+    events: Event[];
+    rest: string;
+};
+/** One line of the file. Never contains a newline, whatever a subject holds. */
+export declare const serialize: (event: Event) => string;
+export {};

package/types/core/paths.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Where a project's ledger lives on disk.
+ *
+ * Pure: creates nothing, reads nothing, and takes its environment as an argument — as Review's
+ * `core/store/paths.ts` does, which this mirrors.
+ *
+ * **Outside the project.** What you have approved is about you, not the work; a ledger in the repo
+ * would turn up in `git status` and, worse, travel to everyone who clones it — trust you earned would
+ * answer for them.
+ *
+ * **Keyed by the project's full path.** The readable part is the last two segments, which tells two
+ * checkouts apart at a glance but not for certain (`~/a/web` and `~/b/web`); a short hash of the whole
+ * path makes it certain, so one checkout's trust can never answer in another.
+ */
+export interface TrustPaths {
+    dir: string;
+    /** The append-only ledger: one event per line. */
+    events: string;
+}
+/** Anything that is not plainly a filename becomes a dash. */
+export declare function slug(text: string): string;
+export declare function projectSlug(directory: string): string;
+export declare function shortHash(text: string): string;
+export declare function trustPaths(directory: string, env?: Record<string, string | undefined>): TrustPaths;

package/types/core/policy.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Whether Trust answers a request, and why — a pure function of the request, what config says, and
+ * what the ledger adds up to.
+ *
+ * The order of the questions is the design:
+ *
+ * 1. **Can it be read?** A command line with `$(…)` in it, a permission that exists to make a person
+ *    look (`external_directory`, `doom_loop`): asked, and nothing is counted.
+ * 2. **Did you ask to be asked?** A specific `ask` rule in config matching any part of the request
+ *    holds all of it. So does a `deny`, though OpenCode never lets one reach us.
+ * 3. **Is every part trusted, or allowed by config?** One untrusted command in a line is enough to
+ *    ask: `git status && rm -rf build` is not half-approved. A part is trusted by its own count, or
+ *    by a family you widened for this agent — unless it is one a widening never covers (dangerous,
+ *    writing a file, running another program: `family.outside`). Config's `ask` was settled in 2, so
+ *    it still wins over a widening.
+ *
+ * The answer always carries what an approval of the request would count towards, so a person's
+ * approval of a request Trust declined is counted against exactly what Trust looked at.
+ */
+import { type Context, type Request } from "./keys.ts";
+import { type Item, type State, type Thresholds } from "./ledger.ts";
+import { type ConfigRule } from "./rules.ts";
+export interface Progress {
+    subject: string;
+    danger?: string;
+    have: number;
+    need: number;
+    trusted: boolean;
+    /** Trusted through this widened family rather than by its own count. */
+    via?: string;
+}
+export interface Judgement {
+    /** Trust approves it now. */
+    answer: boolean;
+    /** In words: logged with every answer, shown beside a request Trust left to you. */
+    why: string;
+    /** What a person's approval of this request counts towards. Empty: nothing is counted. */
+    items: Item[];
+    /** Where each counted subject stands, for the sidebar's `2/3`. */
+    progress: Progress[];
+}
+export interface DecideInput {
+    request: Request;
+    context: Context;
+    agent: string;
+    /** OpenCode's rules for this agent (`rules.rulesFrom`). */
+    rules: readonly ConfigRule[];
+    state: State;
+    settings: Thresholds;
+    now: number;
+}
+export declare function decide(input: DecideInput): Judgement;