@secondlayer/shared 11.20.0 → 11.22.0

package/dist/src/archive/range-digest.d.ts

@@ -19,6 +19,27 @@ type FailureClass = (typeof FAILURE_CLASSES)[number];
 declare const RETRY_STATES: readonly ["open", "retrying", "halted", "resolved"];
 type RetryState = (typeof RETRY_STATES)[number];
 type BootstrapSource = "archive" | "genesis" | "import";
+/**
+* How far a subgraph's rows can be checked without trusting the server,
+* derived from its sources and a scan of its handler. Never configured.
+*
+* - `state`: every input is a named state write, provable from block headers.
+*   Handlers run in the deterministic realm. A deployed `state` subgraph is
+*   verifiable: one with any reason is refused at deploy.
+* - `events`: an input (events, prints, tx results, `ctx.client`) needs
+*   re-execution proofs, which are not served yet.
+* - `none`: a source can never be proven as written (trait scope, tip-first
+*   backfill).
+*/
+interface SubgraphVerification {
+	level: "state" | "events" | "none";
+	/** What stands between the subgraph and checkable rows, e.g.
+	*  `print_event source "swaps" needs event proofs` or
+	*  `subgraph.ts:41:12 Date: wall-clock time differs per run`. */
+	reasons: string[];
+	/** What stays unproven even at this level, e.g. tx attribution of writes. */
+	unproven: string[];
+}
 interface BlocksTable {
 	height: number;
 	hash: string;
@@ -179,6 +200,11 @@ interface SubgraphsTable {
 	expires_at: Date | null;
 	/** (event type, contract) probe pairs persisted at deploy for weight classification. */
 	sparse_probe_targets: unknown | null;
+	/** sha256 over everything that shapes rows (schema, handler bundle,
+	*  startBlock, network, runtime). NULL for unbundled or older deploys. */
+	pin: string | null;
+	/** Level derived at deploy. NULL (older deploys) = not verifiable. */
+	verification: SubgraphVerification | null;
 	created_at: Generated<Date>;
 	updated_at: Generated<Date>;
 }
@@ -847,6 +873,8 @@ interface Database {
 	sentinel_accounts: SentinelAccountsTable;
 	waitlists: WaitlistsTable;
 	waitlist_signups: WaitlistSignupsTable;
+	api_failed_requests: ApiFailedRequestsTable;
+	feedback_tickets: FeedbackTicketsTable;
 }
 interface ServiceHeartbeatsTable {
 	name: string;
@@ -1055,6 +1083,43 @@ interface WaitlistSignupsTable {
 	created_at: Generated<Date>;
 }
 /**
+* 24h hosted record of a failed API request, keyed by `request_id` and
+* scoped to the account that made it. `query` is redacted before insert.
+*/
+interface ApiFailedRequestsTable {
+	request_id: string;
+	account_id: string;
+	method: string;
+	path: string;
+	status: number;
+	code: string;
+	message: Generated<string>;
+	query: Record<string, unknown>;
+	origin: string | null;
+	created_at: Generated<Date>;
+}
+/**
+* Hosted problem report. `attempted` is the server's own copy of the failed
+* request (never caller-supplied); `status` starts `new` until classified.
+*/
+interface FeedbackTicketsTable {
+	id: Generated<string>;
+	account_id: string;
+	idempotency_key: string | null;
+	request_id: string | null;
+	intent: string;
+	expected: Record<string, unknown> | null;
+	kind_hint: string | null;
+	evidence: Record<string, unknown> | null;
+	attempted: Record<string, unknown> | null;
+	origin: string;
+	status: Generated<"new" | "classified">;
+	route: string | null;
+	classification: Record<string, unknown> | null;
+	classified_at: Date | null;
+	created_at: Generated<Date>;
+}
+/**
 * Cheap, SQL-computed digests over a height range — the basis of a verify that
 * runs in seconds instead of hours.
 *

package/dist/src/archive/semantic-digest-builder.d.ts

@@ -19,6 +19,27 @@ type FailureClass = (typeof FAILURE_CLASSES)[number];
 declare const RETRY_STATES: readonly ["open", "retrying", "halted", "resolved"];
 type RetryState = (typeof RETRY_STATES)[number];
 type BootstrapSource = "archive" | "genesis" | "import";
+/**
+* How far a subgraph's rows can be checked without trusting the server,
+* derived from its sources and a scan of its handler. Never configured.
+*
+* - `state`: every input is a named state write, provable from block headers.
+*   Handlers run in the deterministic realm. A deployed `state` subgraph is
+*   verifiable: one with any reason is refused at deploy.
+* - `events`: an input (events, prints, tx results, `ctx.client`) needs
+*   re-execution proofs, which are not served yet.
+* - `none`: a source can never be proven as written (trait scope, tip-first
+*   backfill).
+*/
+interface SubgraphVerification {
+	level: "state" | "events" | "none";
+	/** What stands between the subgraph and checkable rows, e.g.
+	*  `print_event source "swaps" needs event proofs` or
+	*  `subgraph.ts:41:12 Date: wall-clock time differs per run`. */
+	reasons: string[];
+	/** What stays unproven even at this level, e.g. tx attribution of writes. */
+	unproven: string[];
+}
 interface BlocksTable {
 	height: number;
 	hash: string;
@@ -179,6 +200,11 @@ interface SubgraphsTable {
 	expires_at: Date | null;
 	/** (event type, contract) probe pairs persisted at deploy for weight classification. */
 	sparse_probe_targets: unknown | null;
+	/** sha256 over everything that shapes rows (schema, handler bundle,
+	*  startBlock, network, runtime). NULL for unbundled or older deploys. */
+	pin: string | null;
+	/** Level derived at deploy. NULL (older deploys) = not verifiable. */
+	verification: SubgraphVerification | null;
 	created_at: Generated<Date>;
 	updated_at: Generated<Date>;
 }
@@ -847,6 +873,8 @@ interface Database {
 	sentinel_accounts: SentinelAccountsTable;
 	waitlists: WaitlistsTable;
 	waitlist_signups: WaitlistSignupsTable;
+	api_failed_requests: ApiFailedRequestsTable;
+	feedback_tickets: FeedbackTicketsTable;
 }
 interface ServiceHeartbeatsTable {
 	name: string;
@@ -1055,6 +1083,43 @@ interface WaitlistSignupsTable {
 	created_at: Generated<Date>;
 }
 /**
+* 24h hosted record of a failed API request, keyed by `request_id` and
+* scoped to the account that made it. `query` is redacted before insert.
+*/
+interface ApiFailedRequestsTable {
+	request_id: string;
+	account_id: string;
+	method: string;
+	path: string;
+	status: number;
+	code: string;
+	message: Generated<string>;
+	query: Record<string, unknown>;
+	origin: string | null;
+	created_at: Generated<Date>;
+}
+/**
+* Hosted problem report. `attempted` is the server's own copy of the failed
+* request (never caller-supplied); `status` starts `new` until classified.
+*/
+interface FeedbackTicketsTable {
+	id: Generated<string>;
+	account_id: string;
+	idempotency_key: string | null;
+	request_id: string | null;
+	intent: string;
+	expected: Record<string, unknown> | null;
+	kind_hint: string | null;
+	evidence: Record<string, unknown> | null;
+	attempted: Record<string, unknown> | null;
+	origin: string;
+	status: Generated<"new" | "classified">;
+	route: string | null;
+	classification: Record<string, unknown> | null;
+	classified_at: Date | null;
+	created_at: Generated<Date>;
+}
+/**
 * v1 canonical byte encoding for chain identity — the shape that lets
 * independently-run runtimes agree on the same block.
 *

package/dist/src/classify/index.d.ts

@@ -0,0 +1,83 @@
+type ClassifierName = "jev" | "kev" | "clef" | "rules";
+type Question = {
+	type: "choice"
+	instructions: string
+	criteria: Record<string, string>
+} | {
+	type: "score"
+	instructions: string
+	criteria: readonly string[]
+} | {
+	type: "boolean"
+	instructions: string
+	criteria: {
+		true: string
+		false: string
+	}
+};
+type Answer = {
+	type: "choice"
+	choice: string
+	probabilities: Record<string, number>
+	confidence: number
+} | {
+	type: "score"
+	score: number
+	probabilities: Record<string, number>
+	confidence: number
+} | {
+	type: "boolean"
+	probability: number
+	confidence: number
+} | {
+	type: "refusal"
+};
+type Answers<Q extends Record<string, Question>> = { [K in keyof Q] : Answer };
+type ClassifyResult<Q extends Record<string, Question>> = {
+	provider: ClassifierName
+	/** response.modelId when the backend reports one. */
+	modelId: string
+	answers: Answers<Q>
+};
+/** Deterministic answers for the offline provider. Return a value per question
+*  it can decide; omitted questions come back as `{ type: "refusal" }`. */
+type RuleValue = string | number | boolean;
+type RulesFn<Q extends Record<string, Question>> = (state: string | Record<string, unknown>) => { [K in keyof Q]? : RuleValue } | null;
+declare class ClassifierInputError extends Error {
+	constructor(message: string);
+}
+/**
+* One classifier call over jev, kev, clef or offline rules.
+* Returns null on any provider failure (fail-open: callers decide what null
+* means). Only ClassifierInputError, a bad question definition, escapes.
+* Never logs state or response bodies.
+*/
+declare function classify<const Q extends Record<string, Question>>(input: {
+	state: string | Record<string, unknown>
+	questions: Q
+	rules?: RulesFn<Q>
+	/** Overrides resolveProvider(); used by classifier-compare. */
+	provider?: ClassifierName
+	/** Overrides CLASSIFIER_MODEL / the provider default. */
+	modelId?: string
+	/** Default 5000. */
+	timeoutMs?: number
+	env?: Record<string, string | undefined>
+	/** Tests only (kev/clef). */
+	fetchImpl?: typeof fetch
+}): Promise<ClassifyResult<Q> | null>;
+type Env = Record<string, string | undefined>;
+/** CLASSIFIER picks the backend; unset means jev when the gateway key is set,
+*  else offline rules. A backend missing credentials falls back to rules. */
+declare function resolveProvider(env?: Env): {
+	name: ClassifierName
+	modelId: string
+};
+/** (p_max - 1/K) / (1 - 1/K). One option gives 1. */
+declare function choiceConfidence(probabilities: Record<string, number>): number;
+/** max(0, 1 - E|level - mode| / D); D = mean distance of a uniform
+*  distribution over the levels from the middle level. */
+declare function scoreConfidence(probabilities: Record<string, number>, levels: number): number;
+/** Host-defined: |2p - 1|. Not comparable with choice/score confidence. */
+declare function booleanConfidence(p: number): number;
+export { Answer, Answers, ClassifierInputError, ClassifierName, ClassifyResult, Question, RuleValue, RulesFn, booleanConfidence, choiceConfidence, classify, resolveProvider, scoreConfidence };