@looply/sdk 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vuedale
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,101 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @looply/sdk
+
+A typed client for the looply HTTP API.
+
+looply runs long autonomous coding sessions on your own machine. The daemon does
+the work; the server holds the record of it — goals, the queue, what a run did,
+and the decisions a person still has to make. This package is how a program
+outside looply reads that record and takes part in those decisions.
+
+```bash
+npm install @looply/sdk
+```
+
+## Using it
+
+```ts
+import { LooplyClient } from '@looply/sdk';
+
+const looply = new LooplyClient({
+  baseUrl: 'https://api.looply.dev',
+  getToken: () => process.env.LOOPLY_TOKEN ?? null,
+});
+
+const [project] = await looply.projects();
+const goals = await looply.goals(project.id, 'active');
+
+for (const goal of goals) {
+  const report = await looply.autonomy(project.id, goal.id);
+  console.log(goal.text, report.autonomy.length, 'grant(s)');
+}
+```
+
+`getToken` is called for **every** request rather than read once, so a rotated
+credential is picked up without rebuilding the client. `onUnauthorized` is called
+on a 401, so a shell can drop to sign-in instead of retrying a dead token.
+
+`fetch` is injectable and the package has no runtime dependencies — tests need no
+network, and no version of `node-fetch` is imposed on you.
+
+## What it can do
+
+| | |
+| --- | --- |
+| `projects()` | the projects this credential can see |
+| `goals()` · `goal()` · `createGoal()` · `patchGoal()` | what you want done |
+| `startGoal()` · `commandStatus()` | ask for work, and follow the request |
+| `items()` · `status()` | the queue, and what a run is doing |
+| `approvals()` · `approval()` · `decideApproval()` | consequential acts awaiting a person |
+| `execution()` · `resolveExecution()` | governed executions awaiting a person |
+| `autonomy()` | what a goal is authorised to pursue, and under whose grant |
+| `events()` | the ledger, as it happened |
+
+## Two things worth knowing before you build on this
+
+**Approvals and executions refuse a machine token, by design.** An agent
+authorising its own consequential act, or settling its own ambiguity, is the
+thing they exist to prevent. `decideApproval` and `resolveExecution` require a
+credential belonging to a person. A machine credential gets a 403, and that is
+the feature.
+
+**Nothing from `@looply/core` is re-exported here.** Core is the internal shared
+vocabulary of the server, the CLI and the app, and it changes when they need it
+to. Every type this package promises is declared in its own `views.ts`, so
+depending on the SDK does not pin you to a release cycle you cannot see.
+
+## Errors
+
+Every failure is a `LooplyError` carrying a `code`, so you can branch on the
+reason rather than parsing a message:
+
+```ts
+import { LooplyError, isRetryable } from '@looply/sdk';
+
+try {
+  await looply.decideApproval(projectId, approvalId, {
+    decision: 'approve',
+    // Required. Retry safety comes from this OCC token rather than from an
+    // idempotency key: if the first call landed, the version has moved and the
+    // retry is a 409 that tells you so instead of deciding twice.
+    expectedVersion: approval.version,
+  });
+} catch (e) {
+  if (e instanceof LooplyError && isRetryable(e.code)) {
+    // timeout or unavailable — trying again is reasonable
+  }
+}
+```
+
+`isRetryable` takes the **code**, not the error, and is the honest answer to "is
+trying again worth anything?" — a 403 is not retryable however many times you
+ask.
+
+## Stability
+
+**0.x.** The surface may change in a minor version. Every export in `index.ts` is
+a deliberate promise — there is no `export *` — but the promise is a 0.x one
+until an external consumer exists to hold it to.
+
+## Licence
+
+MIT. See [LICENSE](./LICENSE).

package/dist/client.d.ts

@@ -0,0 +1,430 @@
+import type { ApprovalView, CommandStatusView, GoalView, GovernedExecutionView, ItemView, KeeperAnswerView, PageView, PlatformEventView, ProjectView, RunStatusView, GoalAutonomyReport, GoalEvidenceView, PresenceView, SourceClassificationView, SourceDetailView, EvidenceAnchorView, RequirementLinkView, SourceAttestationView, SessionControlGrantView, SourceCoverageView, SourceDispositionView, SourceKindView, SourceView } from './views';
+/**
+ * LOOPLY, AS A PROGRAM OUTSIDE IT SEES IT.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * 🔴 THIS IS THE HUMAN/BUSINESS SURFACE. IT IS NOT THE MACHINE ONE.
+ *
+ * A daemon claims approvals, begins executions and settles them. Those are
+ * MACHINE authority and they are deliberately absent here — not hidden behind a
+ * flag, not available with a different token, absent. Phase 7's whole property
+ * is that one approval yields at most one claim yields at most one execution,
+ * and the cheapest way to lose it is a convenient client method that lets a
+ * caller do the machine's half.
+ *
+ * So there is no `claim()`, no `beginExecution()`, no `settle()`, and no
+ * `popCommand()`. A client that needs them is a daemon, and a daemon has
+ * `packages/cli`.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * 🔴 EVERY MUTATION TAKES AN IDEMPOTENCY KEY, AND THAT IS NOT POLITENESS
+ *
+ * An external caller loses responses. It times out, it retries, its process
+ * restarts mid-request. Without a key, "create a goal" becomes two goals and —
+ * far worse — "start" becomes two Runs, spending two units of a person's
+ * autonomy budget for one instruction. The server already keys goal creation on
+ * `clientRef`; this makes the pattern uniform so no caller has to notice which
+ * routes are safe.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * WHAT IS DELIBERATELY NOT HERE
+ *
+ * ⚠️ MEMORY, INDEX AND GRAPH ARE MACHINE-LOCAL AND ARE NOT EXPOSED. Phase 11's
+ * memory, Phase 12's index and Phase 13's graph live in `.looply/state` on the
+ * developer's own machine, and they describe their private source code — an
+ * index names every file and symbol in the repository. Serving them from this
+ * API would mean shipping that to a server that does not have it today, which
+ * is a privacy regression dressed as a feature. See `docs/PLATFORM.md`.
+ */
+export interface LooplyClientOptions {
+    readonly baseUrl: string;
+    /**
+     * Called for every request, so a rotated credential is picked up without
+     * rebuilding the client.
+     */
+    readonly getToken: () => string | null;
+    /** Called on a 401 so a shell can drop to sign-in rather than retrying. */
+    readonly onUnauthorized?: () => void;
+    readonly timeoutMs?: number;
+    /** Injected so this package has no runtime dependency and tests need no network. */
+    readonly fetch?: typeof globalThis.fetch;
+}
+export declare class LooplyClient {
+    private readonly opts;
+    private readonly http;
+    constructor(opts: LooplyClientOptions);
+    /**
+     * ⚠️ THIS ROUTE ANSWERS A BARE ARRAY, NOT `{ projects }`.
+     *
+     * 🔴 THE FIRST DRAFT UNWRAPPED AN ENVELOPE THAT DOES NOT EXIST, and returned
+     * `undefined` typed as `ProjectView[]` — the cast asserted the envelope into
+     * being and TypeScript had nothing to object to. It was caught by
+     * `sdk-flagship.e2e.spec.ts`, which drives this client against a REAL server;
+     * a suite that mocked `fetch` would have returned whatever shape this method
+     * asked for and agreed with itself all the way to production.
+     */
+    projects(): Promise<readonly ProjectView[]>;
+    /**
+     * Create a goal, at most once per key.
+     *
+     * 🔴 `clientRef` IS THE IDEMPOTENCY KEY AND IT IS REQUIRED. There is no
+     * DELETE for a goal, so a duplicate from a retried POST is permanent. Sending
+     * the same key with the SAME text returns the same goal; sending it with
+     * DIFFERENT text is a conflict, because the key was a promise about which
+     * request this is.
+     */
+    createGoal(projectId: string, input: {
+        readonly clientRef: string;
+        readonly text: string;
+        /** "B after A": ids of goals of the same project. Refused if unknown, itself, or a cycle (named). */
+        readonly dependsOn?: readonly string[];
+        /** Repository regions this goal may write to; canonicalised by the server. */
+        readonly surfaces?: readonly string[];
+        /** Which requirements and constraints of the project's sources this goal serves. */
+        readonly requirements?: readonly RequirementLinkView[];
+    }): Promise<GoalView>;
+    goal(projectId: string, goalId: string): Promise<GoalView>;
+    goals(projectId: string, state?: GoalView['state']): Promise<readonly GoalView[]>;
+    /**
+     * Hand a document over, at most once per key AND at most once per content.
+     *
+     * A source is stored verbatim and content-addressed: the same bytes under a
+     * fresh `clientRef` answer with the source that already exists, and the same
+     * `clientRef` with different bytes is a conflict. What comes back is the
+     * stored record with its anchored statements — the extractor's answer, so a
+     * caller can see what Looply read before anything is built on it.
+     *
+     * ⚠️ `kind` is `markdown`, `text` or `pdf`. The text kinds send `content`;
+     * a `pdf` sends the `pages` of its text layer (as read on the machine that
+     * holds the file) and may carry the file's own sha256 as `originSha256`.
+     */
+    createSource(projectId: string, input: {
+        readonly clientRef: string;
+        readonly name: string;
+        readonly kind: SourceKindView;
+        readonly content?: string;
+        readonly pages?: readonly {
+            readonly page: number;
+            readonly text: string;
+        }[];
+        readonly originSha256?: string;
+    }): Promise<SourceDetailView>;
+    /**
+     * Classify a source with the current classifier version, once.
+     *
+     * Idempotent per version: the rows that exist are answered as they are.
+     * What comes back says what each statement IS; nothing here says what the
+     * repository has done about it.
+     */
+    classifySource(projectId: string, sourceId: string): Promise<{
+        classifications: readonly SourceClassificationView[];
+        classifierVersion: number;
+        created: boolean;
+    }>;
+    /**
+     * Record where each requirement of a source stands against the repository,
+     * as measured at one committed tree — once per (tree, reconciler version).
+     *
+     * The measurement is made where the project index lives (the machine that
+     * holds the repository; `looply source reconcile` is the usual caller) with
+     * `@looply/core`'s `reconcileStatements`; the server stores it verbatim and
+     * recomputes nothing. A second hand-over of the same tree answers the rows
+     * on record (`created: false`).
+     *
+     * 🔴 `implemented-and-evidenced` and `partial` are REFUSED here (400): a
+     * rule cannot put them on record. They are a person's attestation with
+     * evidence, which is a different act.
+     */
+    reconcileSource(projectId: string, sourceId: string, input: {
+        readonly treeSha: string;
+        readonly reconcilerVersion: number;
+        readonly dispositions: readonly SourceDispositionView[];
+    }): Promise<{
+        dispositions: readonly SourceDispositionView[];
+        treeSha: string;
+        reconcilerVersion: number;
+        created: boolean;
+    }>;
+    /**
+     * Say, as a person, that a requirement is implemented-and-evidenced or
+     * partial — with at least one evidence anchor, at the committed tree the
+     * evidence was read at.
+     *
+     * 🔴 THIS NEEDS A DEVICE TOKEN. A machine token is refused (403): the machine
+     * measures (`reconcileSource`), a person vouches. A measurement's values are
+     * refused here (400). The same person saying the same thing at the same tree
+     * is one act: a repeat answers the record with `created: false`.
+     */
+    attestSource(projectId: string, sourceId: string, input: {
+        readonly ordinal: number;
+        readonly disposition: 'implemented-and-evidenced' | 'partial';
+        readonly treeSha: string;
+        readonly anchors: readonly EvidenceAnchorView[];
+        readonly note?: string;
+    }): Promise<{
+        attestation: SourceAttestationView;
+        created: boolean;
+    }>;
+    /**
+     * What is covered and by whom: every requirement and constraint of a source
+     * with the goals that serve it, where it stands, what a person attested, and
+     * one word each. A read; nothing here is written by anyone.
+     */
+    coverage(projectId: string, sourceId: string): Promise<SourceCoverageView>;
+    /**
+     * Every session-control grant this project has issued, live and historical.
+     *
+     * 🔴 THE MACHINE READS THESE AND WRITES NONE OF THEM. `OWNER_CHARTER.md` §5
+     * F-14 is explicit that only the server may issue one — a machine that could
+     * mint its own would be granting itself authority over a session, which is
+     * the whole thing the grant exists to prevent. So there is a reader here and
+     * deliberately no `issueSessionGrant`: issuing is a person's act, from a
+     * person's device, against the route that stamps their principal onto it.
+     */
+    sessionGrants(projectId: string): Promise<readonly SessionControlGrantView[]>;
+    /**
+     * Record that a session acknowledged a grant, through the channel it came on.
+     *
+     * ⚠️ THE CHANNEL IS CLAIMED, NOT PROVED, AND THAT IS WHY IT IS RECORDED
+     * RATHER THAN TRUSTED. A session's adapter and a person's terminal can hold
+     * the same device token — the token says which DEVICE, never which program.
+     * So this writes down what arrived and `controlVerdict` in core refuses
+     * anything that is not `adapter`, which turns a person's attempt into a fact
+     * on the record instead of an inference nobody can check.
+     */
+    acknowledgeSessionGrant(projectId: string, grantId: string, ack: {
+        readonly handshakeNonce: string;
+        readonly sessionId: string;
+        readonly workspace: string;
+        readonly repositoryId: string;
+        readonly scope: readonly string[];
+        readonly via: 'adapter' | 'operator';
+    }): Promise<SessionControlGrantView>;
+    /** A project's sources, newest first, without their content. */
+    sources(projectId: string): Promise<readonly SourceView[]>;
+    /** One source, verbatim, with its anchored statements, their latest classifications and the most recent reconciliation. */
+    source(projectId: string, sourceId: string): Promise<SourceDetailView>;
+    /**
+     * Ask Looply to work on a goal, once.
+     *
+     * 🔴 ONE EXPLICIT START ≤ ONE RUN, AND A LOST RESPONSE MUST NOT SPEND TWO.
+     * `clientRef` is what makes a retry safe: the same key names the same act of
+     * permission, so a repeat returns the command the first call created rather
+     * than authorising a second Start.
+     *
+     * ⚠️ IT IS REQUIRED HERE THOUGH THE SERVER TREATS IT AS OPTIONAL. The server
+     * has to accept keyless commands because the phone and the CLI have always
+     * sent none; an SDK written today has no such history and no reason to offer
+     * the unsafe shape. A caller who genuinely wants at-least-once can pass a
+     * fresh key each time — deliberately, rather than by omission.
+     *
+     * 🔴 THIS DEFECT WAS FOUND BY WRITING THIS METHOD. `POST /v1/commands` had no
+     * key at all, and the daemon derives a Start's request id from the COMMAND
+     * ID, so a retried enqueue was a second Start spending a second ordinal of a
+     * person's autonomy budget. Phase 15 added the key to the server.
+     */
+    startGoal(projectId: string, goalId: string, input: {
+        readonly clientRef: string;
+        /**
+         * Wait for the machine up to this ISO instant (at most 7 days ahead)
+         * instead of the default hour. For an unattended caller: a laptop with
+         * its lid shut picks the Start up when it wakes, or it expires visibly.
+         */
+        readonly deliverBy?: string;
+    }): Promise<{
+        readonly commandId: string;
+    }>;
+    /**
+     * Is the machine that holds this project awake? A Start is delivered by the
+     * machine polling, so this is the first half of "will my Start run".
+     */
+    presence(projectId: string): Promise<PresenceView>;
+    /**
+     * What became of a command.
+     *
+     * `startGoal` returns an id and then goes quiet; this is the durable answer —
+     * started, terminally refused, and why.
+     *
+     * ⚠️ COMMAND TRUTH ONLY. `done` on a start-run means the Start reached its
+     * success boundary, NOT that the run finished or the goal was met. A caller
+     * wanting the whole picture composes this with `status()` and `events()`.
+     */
+    commandStatus(projectId: string, commandId: string): Promise<CommandStatusView>;
+    /** Amend or abandon a goal. `version` is the OCC token the read returned. */
+    patchGoal(projectId: string, goalId: string, input: {
+        readonly state?: GoalView['state'];
+        readonly text?: string;
+        /** Replaces the list. Bumps the version like a change of words. */
+        readonly dependsOn?: readonly string[];
+        readonly surfaces?: readonly string[];
+        /** Replaces the set of requirements this goal serves. */
+        readonly requirements?: readonly RequirementLinkView[];
+        readonly version: number;
+    }): Promise<GoalView>;
+    items(projectId: string): Promise<readonly ItemView[]>;
+    /**
+     * The current run, as a projection.
+     *
+     * ⚠️ THERE IS NO `/runs` COLLECTION, so this SDK does not pretend to one. The
+     * server keeps a single latest-run projection per project — which is what the
+     * product actually shows — and run HISTORY lives in the event ledger, reached
+     * through `events()`.
+     */
+    status(projectId: string): Promise<RunStatusView>;
+    /**
+     * Ask the keeper about a project (DESIGN §9 read path).
+     *
+     * A POST that READS. The question travels in the body rather than a query
+     * string, because a sentence about somebody's codebase does not belong in an
+     * access log — and because the answer quotes item titles, commit shas and the
+     * implementer's own round notes, it needs the same grant `status()` does.
+     *
+     * ⚠️ NOTHING HERE ACTS. The keeper’s write path is deliberately not a second
+     * set of methods: an intent goes through the routes a person already uses —
+     * `command()`, `patchItem()`, answering a question — with `actor: keeper` on
+     * the record, so there is no privileged path for it to take.
+     */
+    ask(projectId: string, question: string): Promise<KeeperAnswerView>;
+    /**
+     * ⚠️ THE APPROVAL ROUTES ANSWER BARE VALUES, NOT ENVELOPES.
+     *
+     * The goal and queue routes DO wrap (`{ goals }`, `{ items }`) and these do
+     * not. There is no rule to infer here — it is simply how each controller was
+     * written — which is exactly why this client is checked against a running
+     * server rather than against a design document.
+     */
+    approvals(projectId: string): Promise<readonly ApprovalView[]>;
+    approval(projectId: string, approvalId: string): Promise<ApprovalView>;
+    /**
+     * Advise on a pending approval: approve or deny, and why.
+     *
+     * 🔴 THIS IS WHAT AN INTEGRATION CAN DO WITH AN APPROVAL, AND ALL IT CAN DO.
+     * Deciding is a person's authority (`decideApproval` needs an owner's device
+     * token); an integration that has reviewed the action in its own process says
+     * what it concluded here, and the owner is notified and decides with the
+     * advice in front of them. Pending only (a 409 otherwise); latest wins, so a
+     * retry is harmless.
+     */
+    recommendApproval(projectId: string, approvalId: string, input: {
+        readonly decision: 'approve' | 'deny';
+        readonly note?: string;
+    }): Promise<ApprovalView>;
+    /**
+     * Approve or deny one exact action.
+     *
+     * 🔴 A PERSON DOES THIS. A machine credential is refused by the server, and
+     * that refusal is the security content of the route rather than an
+     * inconvenience — the hazard is not the 403, it is somebody meeting it and
+     * widening the guard so a machine can authorise its own work.
+     *
+     * `version` is the approval's OCC token: deciding against a stale one is a
+     * conflict, not a silent overwrite, because the thing being approved may have
+     * expired or been revoked since it was read.
+     */
+    decideApproval(projectId: string, approvalId: string, input: {
+        /**
+         * 🔴 `revoke` IS A REAL DECISION AND THE FIRST DRAFT OMITTED IT. Taking
+         * back an authorisation before it is acted on is exactly the operation a
+         * person most urgently needs, and a client that could not express it
+         * would send them to another device to do it.
+         */
+        readonly decision: 'approve' | 'deny' | 'revoke';
+        /**
+         * 🔴 THE FIELD IS `expectedVersion`, AND SENDING `version` MEANT SENDING
+         * NOTHING. The server requires a whole number here and refuses without
+         * one, so this method would have 400'd on every call. There was no
+         * `requestKey` either — a name this SDK invented for a route that has
+         * never accepted it. Both were found by reading the controller.
+         *
+         * Retry safety comes from the OCC token rather than from a key: if the
+         * first call landed, the version has moved, and the retry is a 409 that
+         * tells the caller so instead of deciding twice.
+         */
+        readonly expectedVersion: number;
+        /** Safe prose from a person, kept with the decision. */
+        readonly note?: string;
+    }): Promise<ApprovalView>;
+    execution(projectId: string, executionId: string): Promise<GovernedExecutionView>;
+    /**
+     * Tell Looply what actually happened, when it could not establish that itself.
+     *
+     * 🔴 THIS CLOSES A GAP PHASE 8 LEFT ON PURPOSE. The resolution route has been
+     * owner-guarded and mutation-covered since Phase 8 and had NO CLIENT — and its
+     * client could not be the CLI, because `server-client.ts` authenticates with a
+     * machine token and the route refuses a machine BY DESIGN. A machine settling
+     * its own ambiguity is the one thing the route exists to prevent. It belongs
+     * to a person, so it belongs here.
+     *
+     * ⚠️ `note` IS PRIVATE HUMAN TESTIMONY. It is why a person believes what they
+     * are asserting, it is kept out of every machine- and model-facing view, and a
+     * client must never render it into anything a model reads.
+     */
+    resolveExecution(projectId: string, executionId: string, input: {
+        readonly outcome?: 'succeeded' | 'failed';
+        /**
+         * ⚠️ NO KEY AND NO VERSION — this route accepts neither, and inventing
+         * one here would be a field the server discards while the caller believes
+         * they are protected by it. What makes a repeat safe is that a resolution
+         * is recorded once and never rewrites `state`.
+         */
+        readonly note?: string;
+    }): Promise<GovernedExecutionView>;
+    /**
+     * Whether autonomous pursuit of a goal is still running, and why it stopped.
+     *
+     * ⚠️ THIS IS THE AUTONOMY VIEW, NOT A SAFETY ENDPOINT. There is no
+     * `/safety` route: a loop-safety hold is enforced ON THE MACHINE, in
+     * `loop-safety-store.ts`, and never travels to the server. What the server
+     * knows is that pursuit ENDED and the reason it was given — which is what a
+     * person needs to see, and is version-scoped because a hold on version 4 must
+     * not block version 5.
+     */
+    autonomy(projectId: string, goalId: string): Promise<GoalAutonomyReport>;
+    /**
+     * What the server saw of a goal being delivered, per version.
+     *
+     * This used to say there was no `/evidence` route and that one would be a
+     * server change, not an SDK one. It is now that server change:
+     * `GET …/goals/:goalId/evidence` stitches, once, the runs that pursued each
+     * version, every round's commit with the gate's and the prover's verdicts,
+     * where each pursuit came to rest, and what was pushed under an approval.
+     *
+     * ⚠️ NOT THE MACHINE'S PROOF. Whether a goal was met is decided on the
+     * machine; this is what reached the server. Render `pursuits[].state ===
+     * 'satisfied'` as the machine's claim and `landed` as the commits behind it —
+     * never as "proven". Whitelisted: no gate output, no prover prose, no remote.
+     */
+    goalEvidence(projectId: string, goalId: string): Promise<GoalEvidenceView>;
+    /**
+     * One page of events, resuming from a cursor.
+     *
+     * 🔴 REST REPLAY IS THE CORRECTNESS PATH; A SOCKET IS ONLY AN ACCELERATOR. A
+     * client that has been away — asleep, offline, restarted — reconstructs by
+     * paging from the last cursor it stored. A live stream that missed an event
+     * has no way to notice, so it may never be the only way state arrives.
+     *
+     * ⚠️ DUPLICATES ARE SAFE AND EXPECTED. `id` is stable, so a client that has
+     * seen one can drop it; a client that has NOT seen one must not be missing it.
+     * Delivering twice is the cheap failure, and not delivering is the expensive
+     * one.
+     */
+    events(projectId: string, opts?: {
+        readonly after?: string;
+        readonly limit?: number;
+    }): Promise<PageView<PlatformEventView>>;
+    /**
+     * 🔴 THE QUERY IS A SEPARATE ARGUMENT, NEVER INTERPOLATED INTO `path`.
+     *
+     * `path` is therefore always a literal route with parameter slots and nothing
+     * else, which is what lets `boundary.spec.ts` compare it to the server's route
+     * table exactly rather than by heuristic. An earlier version appended
+     * `${q}` inside the template and the guard could not tell a query suffix from
+     * a path segment — it read `/goals?state=x` as a route called `/goals:param`.
+     * Fixing the guard's parser instead would have left the ambiguity in place for
+     * the next method to trip over.
+     *
+     * `undefined` values are dropped rather than sent as the string "undefined".
+     */
+    private request;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

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