runbios-sdk 0.2.1-rc.143 → 0.2.1-rc.151

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import type { BiOSConfig, ApiErrorBody, AvailableGpuAlternative, CapacityMinimumRequirement } from './types.js';
+import type { BiOSConfig, ApiErrorBody, AvailableGpuAlternative, CapacityMinimumRequirement, LoopImportResult } from './types.js';
 /**
  * Typed error thrown by every SDK method when the API returns a non-2xx status.
  *
@@ -135,6 +135,53 @@ export declare const COMING_SOON_CODES: readonly ["TRAINING_COMING_SOON", "DATAS
 export declare class ComingSoonError extends ApiError {
     constructor(status: number, body: ApiErrorBody);
 }
+/** The code an import answers with when some rows were understood and then could not be stored. */
+export declare const IMPORT_INCOMPLETE_CODE = "IMPORT_INCOMPLETE";
+/**
+ * An import that did not finish: some rows could not be stored, or some
+ * verdicts that arrived with them could not be written.
+ *
+ * The rows it names were read and understood, so there is nothing to fix in
+ * the file: this is a storage failure, not a shape one. The full outcome is on
+ * {@link LoopImportIncompleteError.outcome} — what landed, which conversations
+ * it became, and which row positions did not — because a failure that reports
+ * only "it failed" leaves the caller with no move except sending everything
+ * again.
+ *
+ * HOW TO RECOVER. Send the same rows again with `importId`, the token this
+ * call was filed under. That is what makes the second call a RETRY: rows that
+ * already arrived come back under `already_present` instead of being stored
+ * twice, and a verdict that failed to write is attempted again. Repeat it
+ * exactly; a call that repeats nothing is a second import, on purpose, because
+ * a repeat is otherwise indistinguishable from the next page of a longer file.
+ *
+ * THE WHOLE FILE, not the rows this names, unless you sent `row_ids`. Without
+ * them a row is identified by its place in the call, so a shorter list moves
+ * every row after the gap and each is imported again.
+ */
+export declare class LoopImportIncompleteError extends ApiError {
+    /** Counts, notes and ids for the import, in the same shape a success returns. */
+    readonly outcome: LoopImportResult;
+    constructor(status: number, body: ApiErrorBody);
+    /**
+     * The token to repeat as `import_id` to retry this call. Without it the retry
+     * is a second import rather than a retry, and what already landed is stored
+     * again.
+     */
+    get importId(): string | undefined;
+    /**
+     * Row positions that were not stored, counting from 1 in the order you sent
+     * them. They say what is missing; they are a smaller file to send back only
+     * if you sent `row_ids`.
+     */
+    get notSavedRows(): number[];
+    /**
+     * Row positions whose conversation stored and whose verdict did not. Those
+     * conversations are in the loop waiting for review; retrying records the
+     * verdict.
+     */
+    get verdictsNotSavedRows(): number[];
+}
 /** Whether a machine code is one of the permanent GPU rejections. */
 export declare function isPermanentGpuCode(code: string | undefined): boolean;
 /**

package/dist/client.js

@@ -191,6 +191,63 @@ export class ComingSoonError extends ApiError {
         this.name = 'ComingSoonError';
     }
 }
+/** The code an import answers with when some rows were understood and then could not be stored. */
+export const IMPORT_INCOMPLETE_CODE = 'IMPORT_INCOMPLETE';
+/**
+ * An import that did not finish: some rows could not be stored, or some
+ * verdicts that arrived with them could not be written.
+ *
+ * The rows it names were read and understood, so there is nothing to fix in
+ * the file: this is a storage failure, not a shape one. The full outcome is on
+ * {@link LoopImportIncompleteError.outcome} — what landed, which conversations
+ * it became, and which row positions did not — because a failure that reports
+ * only "it failed" leaves the caller with no move except sending everything
+ * again.
+ *
+ * HOW TO RECOVER. Send the same rows again with `importId`, the token this
+ * call was filed under. That is what makes the second call a RETRY: rows that
+ * already arrived come back under `already_present` instead of being stored
+ * twice, and a verdict that failed to write is attempted again. Repeat it
+ * exactly; a call that repeats nothing is a second import, on purpose, because
+ * a repeat is otherwise indistinguishable from the next page of a longer file.
+ *
+ * THE WHOLE FILE, not the rows this names, unless you sent `row_ids`. Without
+ * them a row is identified by its place in the call, so a shorter list moves
+ * every row after the gap and each is imported again.
+ */
+export class LoopImportIncompleteError extends ApiError {
+    /** Counts, notes and ids for the import, in the same shape a success returns. */
+    outcome;
+    constructor(status, body) {
+        super(status, body);
+        this.name = 'LoopImportIncompleteError';
+        this.outcome = body;
+    }
+    /**
+     * The token to repeat as `import_id` to retry this call. Without it the retry
+     * is a second import rather than a retry, and what already landed is stored
+     * again.
+     */
+    get importId() {
+        return this.outcome.import_id;
+    }
+    /**
+     * Row positions that were not stored, counting from 1 in the order you sent
+     * them. They say what is missing; they are a smaller file to send back only
+     * if you sent `row_ids`.
+     */
+    get notSavedRows() {
+        return this.outcome.not_saved_rows ?? [];
+    }
+    /**
+     * Row positions whose conversation stored and whose verdict did not. Those
+     * conversations are in the loop waiting for review; retrying records the
+     * verdict.
+     */
+    get verdictsNotSavedRows() {
+        return this.outcome.verdicts_not_saved_rows ?? [];
+    }
+}
 /** Whether a machine code is one of the permanent GPU rejections. */
 export function isPermanentGpuCode(code) {
     return typeof code === 'string' && PERMANENT_GPU_CODES.includes(code);
@@ -225,6 +282,12 @@ export function buildApiError(status, body) {
     if (code && COMING_SOON_CODES.includes(code)) {
         return new ComingSoonError(status, body);
     }
+    // A half-finished import carries its whole outcome in the body. Leaving it as
+    // a plain ApiError makes the counts reachable only by casting `.body`, which
+    // is the same as not publishing them.
+    if (code === IMPORT_INCOMPLETE_CODE) {
+        return new LoopImportIncompleteError(status, body);
+    }
     return new ApiError(status, body);
 }
 // ============================================================================

package/dist/index.d.ts

@@ -36,7 +36,7 @@ import { Loop } from './resources/loop.js';
  * SDK version. Sent as part of the User-Agent header.
  * Must match package.json "version" -- enforced by a contract test.
  */
-export declare const VERSION = "0.2.1-rc.143";
+export declare const VERSION = "0.2.1-rc.151";
 export declare class RunBiOS {
     /** Search models, fetch configs, check adapter compatibility. */
     readonly models: Models;
@@ -67,7 +67,7 @@ export declare class RunBiOS {
 }
 /** @deprecated Use {@link RunBiOS}. */
 export { RunBiOS as BiOS };
-export { ApiError, GpuRejectionError, CapacityUnavailableError, ComingSoonError, CAPACITY_UNAVAILABLE_CODE, COMING_SOON_CODES, PERMANENT_GPU_CODES, isPermanentGpuCode, gpuRejectionCodeForReason, } from './client.js';
+export { ApiError, GpuRejectionError, CapacityUnavailableError, ComingSoonError, LoopImportIncompleteError, CAPACITY_UNAVAILABLE_CODE, COMING_SOON_CODES, IMPORT_INCOMPLETE_CODE, PERMANENT_GPU_CODES, isPermanentGpuCode, gpuRejectionCodeForReason, } from './client.js';
 export { Models } from './resources/models.js';
 export { Datasets } from './resources/datasets.js';
 export { Integrations, type HuggingFaceIntegration, type IntegrationBrowseParams } from './resources/integrations.js';

package/dist/index.js

@@ -36,7 +36,7 @@ import { Loop } from './resources/loop.js';
  * SDK version. Sent as part of the User-Agent header.
  * Must match package.json "version" -- enforced by a contract test.
  */
-export const VERSION = '0.2.1-rc.143';
+export const VERSION = '0.2.1-rc.151';
 export class RunBiOS {
     /** Search models, fetch configs, check adapter compatibility. */
     models;
@@ -95,7 +95,7 @@ export { RunBiOS as BiOS };
 // ---------------------------------------------------------------------------
 // Re-exports
 // ---------------------------------------------------------------------------
-export { ApiError, GpuRejectionError, CapacityUnavailableError, ComingSoonError, CAPACITY_UNAVAILABLE_CODE, COMING_SOON_CODES, PERMANENT_GPU_CODES, isPermanentGpuCode, gpuRejectionCodeForReason, } from './client.js';
+export { ApiError, GpuRejectionError, CapacityUnavailableError, ComingSoonError, LoopImportIncompleteError, CAPACITY_UNAVAILABLE_CODE, COMING_SOON_CODES, IMPORT_INCOMPLETE_CODE, PERMANENT_GPU_CODES, isPermanentGpuCode, gpuRejectionCodeForReason, } from './client.js';
 export { Models } from './resources/models.js';
 export { Datasets } from './resources/datasets.js';
 export { Integrations } from './resources/integrations.js';

package/dist/resources/loop.d.ts

@@ -84,6 +84,37 @@ export declare class Loop {
      * filed under: "everything in one bucket called import" is a corpus nobody
      * can slice afterwards. At most 5000 rows per call, because the call is
      * synchronous and somebody is waiting on it.
+     *
+     * WHAT COMES BACK. `imported` is what this call created and `trace_ids` names
+     * the conversations from the file that are now in the loop, so a caller can
+     * label, review or delete them. `by_shape`, `reviewed` and `needs_review`
+     * count what THIS CALL created, not what was merely recognised and not rows
+     * an earlier import already had, and the sentences in `notes` are written
+     * from those counts, so the numbers and the prose describe the same call and
+     * a re-send cannot report a reviewed conversation as waiting for review.
+     * `refused` is rows whose shape could not be read, which the file fixes;
+     * `not_saved` is rows that were understood and then could not be stored,
+     * which the file cannot fix.
+     *
+     * A call with any `not_saved`, or any `verdicts_not_saved` (the conversation
+     * stored and the judgement that came with it did not), REJECTS with
+     * `LoopImportIncompleteError`, whose `outcome` carries all of the above and
+     * whose `notSavedRows` and `verdictsNotSavedRows` name the positions.
+     *
+     * HOW A RETRY IS SAFE. Every response carries `import_id`, the token this
+     * call was filed under. Send the same rows again with it, and rows that
+     * already arrived come back on `already_present` instead of being stored
+     * twice, while a verdict that failed to write is attempted again. A call that
+     * repeats no token is its own import, deliberately: two calls carrying the
+     * same rows are as likely to be two pages of one export as one call twice,
+     * and guessing "retry" silently drops the second copy of every conversation a
+     * file lists more than once.
+     *
+     * SENDING A FILE IN PAGES. Either give each row its own `row_ids` entry, and
+     * then chunking, ordering and subsets all stop mattering; or send one
+     * `import_id` with the `row_offset` each page starts at. Do not send back
+     * only the rows `notSavedRows` names unless you used `row_ids`: without them
+     * a shorter list moves every row after the gap and imports it again.
      */
     importRows(params: LoopImportParams): Promise<LoopImportResult>;
     /** List captured conversations, newest first. */
@@ -212,7 +243,22 @@ export declare class Loop {
         key: string;
         label: string;
     }>;
-    /** Every label in the workspace, with how many conversations carry it. */
+    /**
+     * Every label in the workspace, with how many conversations carry it and
+     * which master groups those conversations are in.
+     *
+     * TWO FIELDS ANSWER THE GROUP QUESTION, AND THEY ANSWER DIFFERENT ONES.
+     * `parent` is the group ALL of a label's conversations are in, and it is
+     * null the moment they disagree. `parents` is every group ANY of them are
+     * in, with how many of them are in each.
+     *
+     * Build a list of master groups out of `parents`. A label with 12
+     * conversations, 5 of them under `support`, reports `parent: null` and
+     * `parents: [{parent: 'support', traces: 5}]`, so code that reads only
+     * `parent` sees no group at all for it. The registry used to answer
+     * `parent: "support"` for all twelve, which named the group but put seven
+     * conversations in it that nobody had put there.
+     */
     listLabels(): Promise<LoopLabelCount[]>;
     /**
      * Build a training set from the feedback recorded so far.
@@ -422,11 +468,34 @@ export declare class Loop {
      * scoring something the rubric never asked for, is refused and reported in
      * `rejected` rather than silently dropped.
      *
-     * Pass `finish` to close a run you have decided to stop early. Without it an
-     * unfinished run stays open, which is the honest state for work that was
-     * abandoned rather than completed.
+     * Pass `finish` to close the run in the same call once you have nothing left
+     * to send. To close a run WITHOUT scores, call `stopRun`: an empty verdict
+     * list with `finish` does the same thing and reads like a mistake.
      */
     postVerdicts(runId: string, verdicts: LoopJudgeVerdict[], finish?: boolean): Promise<LoopJudgeVerdictResult>;
+    /**
+     * Close a run that has not finished.
+     *
+     * A judge may have one open run of its own at a time, so an open run BLOCKS
+     * the next one, and the runs that most need closing are the ones nobody can
+     * wait out: a run the agent has parked on an empty balance or a refused key
+     * stays open until the reason is fixed or somebody stops it.
+     *
+     * Nothing is deleted. Every verdict already recorded stays recorded, the
+     * counters keep saying how much of the selection was covered, and the
+     * conversations the run was holding are free for the next one. The run ends
+     * as `stopped` rather than `done`, so an interrupted pass and a completed
+     * one do not read alike.
+     *
+     * A run that finished on its own is not rewritten: stopping one answers 409.
+     *
+     * Returns the stopped run itself, like `startRun` and `getRun`, not the
+     * `{run}` envelope the service sends. Every other single-run method in this
+     * class unwraps, and `Loop.stop_run` in the Python SDK does too, so a
+     * caller who wrote `(await loop.stopRun(id)).status` against one of its
+     * siblings is right here as well.
+     */
+    stopRun(runId: string): Promise<LoopJudgeRun>;
     /**
      * Can an agent run here, is one running, and is it on for this workspace.
      * `available` is about the environment; `online` about the worker;
@@ -494,6 +563,14 @@ export declare class Loop {
      *
      * Send the `terms_version` it returns back in `createTrainingRule`. Read the
      * figures out of this response rather than inventing ceilings of your own.
+     *
+     * `valid: false` with an EMPTY `refusals` list is not nothing: check
+     * `unreachable`, which names every peer the platform could not reach. The
+     * rule is savable in that state and would be paused, but the estimate around
+     * it is not trustworthy -- both `worst_hourly_*` are `0` -- so do not quote
+     * those figures to anyone. `model_revision` is NOT a signal here: a degraded
+     * pass echoes back whatever revision the request carried, so test
+     * `unreachable.length > 0` rather than the revision being empty.
      */
     preflightTrainingRule(params: TrainingRulePreflightRequest): Promise<TrainingRulePreflight>;
     /**

package/dist/resources/loop.js

@@ -87,6 +87,37 @@ export class Loop {
      * filed under: "everything in one bucket called import" is a corpus nobody
      * can slice afterwards. At most 5000 rows per call, because the call is
      * synchronous and somebody is waiting on it.
+     *
+     * WHAT COMES BACK. `imported` is what this call created and `trace_ids` names
+     * the conversations from the file that are now in the loop, so a caller can
+     * label, review or delete them. `by_shape`, `reviewed` and `needs_review`
+     * count what THIS CALL created, not what was merely recognised and not rows
+     * an earlier import already had, and the sentences in `notes` are written
+     * from those counts, so the numbers and the prose describe the same call and
+     * a re-send cannot report a reviewed conversation as waiting for review.
+     * `refused` is rows whose shape could not be read, which the file fixes;
+     * `not_saved` is rows that were understood and then could not be stored,
+     * which the file cannot fix.
+     *
+     * A call with any `not_saved`, or any `verdicts_not_saved` (the conversation
+     * stored and the judgement that came with it did not), REJECTS with
+     * `LoopImportIncompleteError`, whose `outcome` carries all of the above and
+     * whose `notSavedRows` and `verdictsNotSavedRows` name the positions.
+     *
+     * HOW A RETRY IS SAFE. Every response carries `import_id`, the token this
+     * call was filed under. Send the same rows again with it, and rows that
+     * already arrived come back on `already_present` instead of being stored
+     * twice, while a verdict that failed to write is attempted again. A call that
+     * repeats no token is its own import, deliberately: two calls carrying the
+     * same rows are as likely to be two pages of one export as one call twice,
+     * and guessing "retry" silently drops the second copy of every conversation a
+     * file lists more than once.
+     *
+     * SENDING A FILE IN PAGES. Either give each row its own `row_ids` entry, and
+     * then chunking, ordering and subsets all stop mattering; or send one
+     * `import_id` with the `row_offset` each page starts at. Do not send back
+     * only the rows `notSavedRows` names unless you used `row_ids`: without them
+     * a shorter list moves every row after the gap and imports it again.
      */
     async importRows(params) {
         return this._http.fetchPost('/api/loop/import', params);
@@ -280,7 +311,22 @@ export class Loop {
         const q = key ? `?key=${encodeURIComponent(key)}` : '';
         return this._http.fetchDelete(`/api/loop/traces/${encodeURIComponent(traceId)}/labels/${encodeURIComponent(label)}${q}`);
     }
-    /** Every label in the workspace, with how many conversations carry it. */
+    /**
+     * Every label in the workspace, with how many conversations carry it and
+     * which master groups those conversations are in.
+     *
+     * TWO FIELDS ANSWER THE GROUP QUESTION, AND THEY ANSWER DIFFERENT ONES.
+     * `parent` is the group ALL of a label's conversations are in, and it is
+     * null the moment they disagree. `parents` is every group ANY of them are
+     * in, with how many of them are in each.
+     *
+     * Build a list of master groups out of `parents`. A label with 12
+     * conversations, 5 of them under `support`, reports `parent: null` and
+     * `parents: [{parent: 'support', traces: 5}]`, so code that reads only
+     * `parent` sees no group at all for it. The registry used to answer
+     * `parent: "support"` for all twelve, which named the group but put seven
+     * conversations in it that nobody had put there.
+     */
     async listLabels() {
         const res = await this._http.fetchGet('/api/loop/labels');
         return res.labels;
@@ -589,13 +635,39 @@ export class Loop {
      * scoring something the rubric never asked for, is refused and reported in
      * `rejected` rather than silently dropped.
      *
-     * Pass `finish` to close a run you have decided to stop early. Without it an
-     * unfinished run stays open, which is the honest state for work that was
-     * abandoned rather than completed.
+     * Pass `finish` to close the run in the same call once you have nothing left
+     * to send. To close a run WITHOUT scores, call `stopRun`: an empty verdict
+     * list with `finish` does the same thing and reads like a mistake.
      */
     async postVerdicts(runId, verdicts, finish = false) {
         return this._http.fetchPost(`/api/loop/runs/${encodeURIComponent(runId)}/verdicts`, { verdicts, finish });
     }
+    /**
+     * Close a run that has not finished.
+     *
+     * A judge may have one open run of its own at a time, so an open run BLOCKS
+     * the next one, and the runs that most need closing are the ones nobody can
+     * wait out: a run the agent has parked on an empty balance or a refused key
+     * stays open until the reason is fixed or somebody stops it.
+     *
+     * Nothing is deleted. Every verdict already recorded stays recorded, the
+     * counters keep saying how much of the selection was covered, and the
+     * conversations the run was holding are free for the next one. The run ends
+     * as `stopped` rather than `done`, so an interrupted pass and a completed
+     * one do not read alike.
+     *
+     * A run that finished on its own is not rewritten: stopping one answers 409.
+     *
+     * Returns the stopped run itself, like `startRun` and `getRun`, not the
+     * `{run}` envelope the service sends. Every other single-run method in this
+     * class unwraps, and `Loop.stop_run` in the Python SDK does too, so a
+     * caller who wrote `(await loop.stopRun(id)).status` against one of its
+     * siblings is right here as well.
+     */
+    async stopRun(runId) {
+        const res = await this._http.fetchPost(`/api/loop/runs/${encodeURIComponent(runId)}/stop`, {});
+        return res.run;
+    }
     // ── the agent ─────────────────────────────────────────────────────────
     //
     // The worker that calls a model on the workspace's behalf: it applies
@@ -700,6 +772,14 @@ export class Loop {
      *
      * Send the `terms_version` it returns back in `createTrainingRule`. Read the
      * figures out of this response rather than inventing ceilings of your own.
+     *
+     * `valid: false` with an EMPTY `refusals` list is not nothing: check
+     * `unreachable`, which names every peer the platform could not reach. The
+     * rule is savable in that state and would be paused, but the estimate around
+     * it is not trustworthy -- both `worst_hourly_*` are `0` -- so do not quote
+     * those figures to anyone. `model_revision` is NOT a signal here: a degraded
+     * pass echoes back whatever revision the request carried, so test
+     * `unreachable.length > 0` rather than the revision being empty.
      */
     async preflightTrainingRule(params) {
         return this._http.fetchPost('/api/loop/training-rules/preflight', params);

package/dist/types.d.ts

@@ -2233,13 +2233,91 @@ export interface LoopImportParams {
     /** Applied to every row: importing a dump is when somebody knows what it is. */
     labels?: string[];
     attributes?: Record<string, string>;
+    /**
+     * Repeat the `import_id` a previous call reported to make this call a RETRY
+     * of that one: rows that already arrived come back under `already_present`
+     * instead of being stored again.
+     *
+     * Leave it out and this call is its own import. The endpoint will NOT guess:
+     * two calls carrying the same rows are as likely to be two pages of one
+     * export as one call sent twice, and guessing "retry" silently drops the
+     * second copy of every conversation a file lists more than once. Every
+     * response carries the token it was filed under, so a retry is always
+     * available and never has to be inferred.
+     *
+     * SEND THE ROWS AS YOU SENT THEM. Without `row_ids` a row is matched on its
+     * text, and the match survives re-ordered keys and different whitespace but
+     * NOT a number that has been re-spelled: `100`, `1e2` and `100.0` are three
+     * different rows. A round trip through most JSON libraries re-spells numbers
+     * (Python turns `1e2` into `100.0`), so a retry built by re-serialising a
+     * parsed file can store rows a second time. Keep the bytes you sent, or send
+     * `row_ids` and stop depending on the text at all.
+     */
+    import_id?: string;
+    /**
+     * Where this page starts in the file, counting from 0. Send it when you split
+     * one import across several calls under one `import_id`, so two pages are not
+     * matched against each other row for row. Ignored when you send `row_ids`.
+     */
+    row_offset?: number;
+    /**
+     * Your own id for each row, in the same order as `rows`: a ticket number, a
+     * conversation id, whatever the export already carries.
+     *
+     * The strongest form of identity, and the one to reach for with a file big
+     * enough to page. It SUPERSEDES `import_id` and `row_offset`: with it,
+     * chunking, ordering and subsets all stop mattering and any part of the file
+     * can be re-sent exactly. One per row or none at all, and no two rows in a
+     * call may share an id: both are refused rather than silently merging two
+     * conversations into one.
+     *
+     * THE ID IS THE IDENTITY, AND THE ROW'S TEXT IS NOT PART OF IT. A row sent
+     * again under an id this source already imported comes back under
+     * `already_present` and the stored conversation is left as it was, even if
+     * you changed its text. A CORRECTION DOES NOT LAND THIS WAY: send it under a
+     * new id. That is the trade for making every retry, page and subset safe -
+     * the text is never compared, so nothing your serialiser does to it can turn
+     * a retry into a second import.
+     */
+    row_ids?: string[];
 }
+/**
+ * What an import did.
+ *
+ * A call where every row stored resolves with this. A call where SOME rows
+ * could not be stored rejects with {@link LoopImportIncompleteError}, whose
+ * `outcome` is this same shape: the counts are the whole answer either way, so
+ * read them from the error exactly as you would from a success.
+ */
 export interface LoopImportResult {
+    /**
+     * The token this call was filed under, whether you sent one or it was minted
+     * for you. Send the same rows again with this `import_id` to retry the call.
+     * Present on every response, success or failure, because a call can succeed
+     * and still need retrying when the answer never reached you.
+     */
+    import_id?: string;
+    /** How many conversations this call created. */
     imported: number;
     /**
-     * How many arrived carrying a verdict. Reported apart from `imported`
-     * because it is the difference between data you can train on and data
-     * somebody still has to look at.
+     * How many rows an earlier call under the SAME `import_id` (or carrying the
+     * same `row_ids`) had already imported, and so were not stored a second time.
+     * Zero on a first import, and zero on any call that repeated neither: a call
+     * that does not say it is a retry is its own import, which is what lets a
+     * file sent in pages land complete.
+     */
+    already_present?: number;
+    /**
+     * How many verdicts THIS CALL WROTE. Reported apart from `imported` because
+     * it is the difference between data you can train on and data somebody still
+     * has to look at.
+     *
+     * Re-sending a row whose verdict already landed writes nothing and counts
+     * nothing, so a plain retry reads 0. Re-sending one that came back in
+     * `verdicts_not_saved` DOES count here when the write succeeds this time,
+     * even though the row itself is counted under `already_present`: that is the
+     * first time anybody recorded that verdict, not a second reviewer. This is
+     * the field to read to confirm a repair landed.
      */
     reviewed: number;
     needs_review: number;
@@ -2251,17 +2329,47 @@ export interface LoopImportResult {
     /**
      * How many rows were understood and then could not be stored. Counted apart
      * from `refused`, because the two are different claims and rewriting a file
-     * that was already correct fixes nothing. A call with any of these fails
-     * rather than succeeding, and the failure carries these same fields.
+     * that was already correct fixes nothing. A call with any of these rejects
+     * rather than resolving; read it off {@link LoopImportIncompleteError.outcome}.
      */
     not_saved?: number;
-    /** How many rows of each recognised shape, so a mis-shaped file is visible. */
+    /**
+     * WHICH rows those were, counting from 1 in the order you sent them, so you
+     * can say what is missing rather than only how much.
+     *
+     * NOT A SMALLER FILE TO SEND BACK unless you sent `row_ids`. Without them a
+     * row is identified by its place in the call, so a shorter list moves every
+     * row after the gap and each one is stored again. Re-send the whole set of
+     * rows, in the same order, with the same `import_id`; what already arrived
+     * comes back under `already_present`. With `row_ids` a row carries its own
+     * identity and any subset is exact.
+     */
+    not_saved_rows?: number[];
+    /**
+     * Rows whose CONVERSATION stored and whose VERDICT did not, and which rows
+     * those were. A preference pair or a thumbs label is two writes, and the
+     * second can fail on its own: the conversation is then in the loop carrying
+     * nobody's judgement, counted under `needs_review` rather than `reviewed`,
+     * and not trainable. The call rejects with {@link LoopImportIncompleteError},
+     * and sending the rows again under the same `import_id` records the verdict
+     * without storing the conversation twice.
+     */
+    verdicts_not_saved?: number;
+    verdicts_not_saved_rows?: number[];
+    /**
+     * How many conversations of each shape THIS CALL created. Rows that were
+     * refused, rows that failed to store and rows an earlier import already had
+     * are not in here: the counts and the sentences in `notes` describe the same
+     * call, so neither can claim a conversation is waiting for review when none
+     * was written.
+     */
     by_shape: Record<string, number>;
     refused_why: Record<string, number>;
     /**
-     * The conversations this call created, in file order. Without them a caller
-     * whose import half-failed has a number and no way to reach what landed: no
-     * way to label it, review it, or delete it and start again.
+     * The conversations from this file that are now in the loop, in file order:
+     * the ones this call created and the ones it found already there. Without
+     * them a caller whose import half-failed has a number and no way to reach
+     * what landed: no way to label it, review it, or delete it and start again.
      */
     trace_ids?: string[];
     notes: string[];
@@ -2350,7 +2458,11 @@ export interface LoopDatasetCreateParams {
     to?: string;
     /** Narrow to one slice. A label with children selects them too. */
     label?: string;
-    /** Take this many at random from what the filters matched. */
+    /**
+     * Take this many of what the filters matched. Which ones is arbitrary but
+     * REPEATABLE: the same conversations always give the same slice, so two
+     * builds of one spec describe the same set.
+     */
     sample?: number;
     /** Holds back your most recent work, not a random slice. 0-50. */
     holdout_percent?: number;
@@ -2535,8 +2647,13 @@ export interface LoopJudgeRun {
      * it for a week and items were still waiting. Nothing is deleted and posting
      * verdicts to it still works and still closes it as done. It exists so that
      * `open` keeps meaning "somebody is working on this".
+     *
+     * `stopped` is a run somebody closed on purpose before it finished, with
+     * `stopRun`. Separate from `done` because a run that covered three of forty
+     * conversations did not finish its work: every score it recorded is kept
+     * either way, and reading one as the other overstates what was evaluated.
      */
-    status: 'open' | 'done' | 'abandoned';
+    status: 'open' | 'done' | 'abandoned' | 'stopped';
     instructions: string;
     dimensions: LoopJudgeDimension[];
     model: string | null;
@@ -2817,9 +2934,34 @@ export interface LoopLabel {
     /** The dimension this value belongs to. `tag` for a bare name. */
     key: string;
 }
+/** One master group, and how many of a label's conversations are in it. */
+export interface LoopLabelParentCount {
+    parent: string;
+    traces: number;
+}
 export interface LoopLabelCount {
     label: string;
+    /**
+     * The master group ALL of this label's conversations are in, and nothing
+     * else. Null when they disagree: the registry used to answer the
+     * alphabetically last parent over a mixed group, so `billing` was reported
+     * under `support` while seven of its twelve conversations were in no group
+     * at all. Render "(in x)" from this field only.
+     */
     parent: string | null;
+    /**
+     * Every master group ANY of them are in, sorted, with how many of this
+     * label's conversations are in each. Empty when there are none.
+     *
+     * Read this, not `parent`, to discover which master groups exist: a label
+     * whose conversations disagree still belongs partly to a real group, and
+     * `parent` is null for it, so a picker built from `parent` alone loses the
+     * group along with the false claim. The count is per group rather than the
+     * label's own total, because adding a label's whole count to its parent is
+     * the same mistake one level down. What is in no group at all is `traces`
+     * minus the sum of these.
+     */
+    parents: LoopLabelParentCount[];
     traces: number;
     key: string;
 }
@@ -3002,6 +3144,22 @@ export interface TrainingRulePreflight {
     eval_ceiling_cents: number;
     warnings: string[];
     refusals: TrainingRulePreflightRefusal[];
+    /**
+     * Every peer the platform could not reach on this pass, one entry each, in
+     * the same `{stage, code, message}` shape as a refusal.
+     *
+     * A warning, not a refusal: an unreachable peer judged nothing, so it never
+     * refuses a save. It is still why the rule cannot fire — both
+     * `worst_hourly_*` come back `0` — so `valid` is `false`. Key a "cannot
+     * save" state on this when `refusals` is empty; the same sentences are also
+     * in `warnings`, so render one or the other.
+     *
+     * Key it on THIS, not on `model_revision`. A degraded pass echoes back the
+     * `model_revision` the request carried rather than emptying it, so
+     * `if (!model_revision)` is false on exactly the passes it was meant to
+     * catch. Use `unreachable.length > 0`, or `/^[0-9a-f]{40}$/`.
+     */
+    unreachable: TrainingRulePreflightRefusal[];
     key_check: TrainingRuleKeyCheck;
     terms_text: string;
     terms_version: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "runbios-sdk",
-  "version": "0.2.1-rc.143",
+  "version": "0.2.1-rc.151",
   "description": "Official TypeScript SDK for the Run BiOS training and deployment platform API",
   "type": "module",
   "main": "./dist/index.js",