@substrat-run/adapter-sqlite 0.149.0 → 0.151.0

package/dist/trace.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The scope host's half of a request trace (#2358): what only the host sees.
+ *
+ * Every function here is a no-op until something installs a sink (`installedTraceSink`), and
+ * `substrat dev` is the only thing that does. The hosted adapter never loads this package, and
+ * a deploy that installs none records nothing, so the cost of tracing on any other path is one
+ * `globalThis` read per invocation.
+ *
+ * Two rules for everything below. A hook never changes what the host does: it reads the
+ * value the host already computed, and a sink that throws is swallowed rather than allowed to
+ * fail a request. And nothing is invented: a deny's `requires` and `callerHas` come from the
+ * role table and the checker's own `holdings`, the same sources a console would read.
+ */
+import { type EntityRef, type RelationTuple, type TraceHeadPatch, type TraceStep } from '@substrat-run/contracts';
+import type { ScopedSql } from '@substrat-run/kernel';
+/** A step as a hook writes it: the host stamps `atMs`. */
+export type TraceStepInput = TraceStep extends infer S ? (S extends TraceStep ? Omit<S, 'atMs'> : never) : never;
+/** One invocation's handle on the installed sink. */
+export interface InvocationTrace {
+    /** Whether the sink asked for the values bound to a statement. */
+    readonly sqlParams: boolean;
+    step(step: TraceStepInput): void;
+    head(patch: TraceHeadPatch): void;
+    /** Milliseconds on the same clock a step's `atMs` reads, for timing a span. */
+    now(): number;
+}
+/**
+ * The handle for an invocation, or `undefined` when tracing is off or the call has no id.
+ * Steps are stamped on the time axis the request layer started (`traceOffsetMs`), so a check
+ * here and an outbound call there sort in the order they happened.
+ */
+export declare function invocationTrace(invocationId: string | null | undefined): InvocationTrace | undefined;
+/** The invocation is over on this host: release its start. (The sink's `end` is the HTTP layer's.) */
+export declare function forgetInvocationTrace(invocationId: string | null | undefined): void;
+export declare const entityString: (entity: EntityRef | undefined | null) => string | null;
+/**
+ * Which path an ALLOW took, read off the proof tuples: a role (`role:<key>`), a system module
+ * (`system:<module>`), or a direct / entity-narrowed grant (`grant:<object>`).
+ */
+export declare function decidedByOf(proof: readonly RelationTuple[]): string | null;
+export declare function tracedSql(sql: ScopedSql, trace: InvocationTrace | undefined, redactText: (text: string) => string, redactValue: <T>(value: T) => T): ScopedSql;
+//# sourceMappingURL=trace.d.ts.map

package/dist/trace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace.d.ts","sourceRoot":"","sources":["../src/trace.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAIL,KAAK,SAAS,EACd,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,SAAS,EACf,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAEtD,0DAA0D;AAC1D,MAAM,MAAM,cAAc,GAAG,SAAS,SAAS,MAAM,CAAC,GAAG,CAAC,CAAC,SAAS,SAAS,GAAG,IAAI,CAAC,CAAC,EAAE,MAAM,CAAC,GAAG,KAAK,CAAC,GAAG,KAAK,CAAC;AAEjH,qDAAqD;AACrD,MAAM,WAAW,eAAe;IAC9B,kEAAkE;IAClE,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,IAAI,CAAC,IAAI,EAAE,cAAc,GAAG,IAAI,CAAC;IACjC,IAAI,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI,CAAC;IAClC,+EAA+E;IAC/E,GAAG,IAAI,MAAM,CAAC;CACf;AAID;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,eAAe,GAAG,SAAS,CAiBpG;AAED,sGAAsG;AACtG,wBAAgB,qBAAqB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI,CAEnF;AAED,eAAO,MAAM,YAAY,WAAY,SAAS,GAAG,SAAS,GAAG,IAAI,KAAG,MAAM,GAAG,IAClB,CAAC;AAE5D;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,GAAG,MAAM,GAAG,IAAI,CAK1E;AAUD,wBAAgB,SAAS,CACvB,GAAG,EAAE,SAAS,EACd,KAAK,EAAE,eAAe,GAAG,SAAS,EAClC,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,EACpC,WAAW,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,KAAK,CAAC,GAC9B,SAAS,CA4BX"}

package/dist/trace.js

@@ -0,0 +1,91 @@
+/**
+ * The scope host's half of a request trace (#2358): what only the host sees.
+ *
+ * Every function here is a no-op until something installs a sink (`installedTraceSink`), and
+ * `substrat dev` is the only thing that does. The hosted adapter never loads this package, and
+ * a deploy that installs none records nothing, so the cost of tracing on any other path is one
+ * `globalThis` read per invocation.
+ *
+ * Two rules for everything below. A hook never changes what the host does: it reads the
+ * value the host already computed, and a sink that throws is swallowed rather than allowed to
+ * fail a request. And nothing is invented: a deny's `requires` and `callerHas` come from the
+ * role table and the checker's own `holdings`, the same sources a console would read.
+ */
+import { forgetTraceStart, installedTraceSink, traceOffsetMs, } from '@substrat-run/contracts';
+const clock = () => performance.now();
+/**
+ * The handle for an invocation, or `undefined` when tracing is off or the call has no id.
+ * Steps are stamped on the time axis the request layer started (`traceOffsetMs`), so a check
+ * here and an outbound call there sort in the order they happened.
+ */
+export function invocationTrace(invocationId) {
+    const sink = installedTraceSink();
+    if (!sink || !invocationId)
+        return undefined;
+    const guard = (fn) => {
+        try {
+            fn();
+        }
+        catch {
+            /* a trace must never fail the request it describes */
+        }
+    };
+    return {
+        sqlParams: sink.capture?.sqlParams === true,
+        step: (step) => guard(() => sink.step(invocationId, { ...step, atMs: traceOffsetMs(invocationId) })),
+        head: (patch) => guard(() => sink.head(invocationId, patch)),
+        now: clock,
+    };
+}
+/** The invocation is over on this host: release its start. (The sink's `end` is the HTTP layer's.) */
+export function forgetInvocationTrace(invocationId) {
+    if (invocationId)
+        forgetTraceStart(invocationId);
+}
+export const entityString = (entity) => entity ? `${entity.entityType}:${entity.entityId}` : null;
+/**
+ * Which path an ALLOW took, read off the proof tuples: a role (`role:<key>`), a system module
+ * (`system:<module>`), or a direct / entity-narrowed grant (`grant:<object>`).
+ */
+export function decidedByOf(proof) {
+    for (const t of proof)
+        if (String(t.subject).startsWith('role:'))
+            return String(t.subject);
+    for (const t of proof)
+        if (String(t.subject).startsWith('system:'))
+            return String(t.subject);
+    for (const t of proof)
+        if (String(t.relation).startsWith('granted:'))
+            return `grant:${String(t.object)}`;
+    return null;
+}
+export function tracedSql(sql, trace, redactText, redactValue) {
+    if (!trace)
+        return sql;
+    const run = (operation, statement, params, call, rows) => {
+        const started = trace.now();
+        const at = (error) => ({
+            type: 'sql',
+            operation,
+            statement: redactText(statement),
+            // Only what the sink asked for: a bound value is as likely a person's data as an id.
+            ...(trace.sqlParams ? { params: redactValue([...params]) } : {}),
+            durationMs: Math.max(0, Math.round(trace.now() - started)),
+            ...(error === undefined ? {} : { error }),
+        });
+        try {
+            const result = call();
+            trace.step({ ...at(), ...rows(result) });
+            return result;
+        }
+        catch (err) {
+            trace.step(at(redactText(err instanceof Error ? err.message : String(err))));
+            throw err;
+        }
+    };
+    return {
+        query: ((statement, params = []) => run('query', statement, params, () => sql.query(statement, params), (r) => ({ rowsRead: r.length }))),
+        exec: ((statement, params = []) => run('exec', statement, params, () => sql.exec(statement, params), (r) => ({ rowsWritten: r.changes }))),
+    };
+}
+//# sourceMappingURL=trace.js.map

package/dist/trace.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@substrat-run/adapter-sqlite",
-  "version": "0.149.0",
+  "version": "0.151.0",
   "description": "Pure-SQLite scope host — real kernel semantics with no Cloudflare dependency (D-14): local dev, CI, self-host/escrow",
   "license": "AGPL-3.0-only",
   "repository": {
@@ -39,17 +39,17 @@
   ],
   "dependencies": {
     "better-sqlite3": "^13.0.3",
-    "@substrat-run/contracts": "^0.149.0",
-    "@substrat-run/kernel": "^0.149.0"
+    "@substrat-run/contracts": "^0.151.0",
+    "@substrat-run/kernel": "^0.151.0"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^9.6.0",
     "hono": "^4.13.13",
     "typescript": "^7.0.0",
-    "vitest": "^5.0.3",
-    "@substrat-run/attachment-extractors": "^0.2.10",
-    "@substrat-run/contract-tests": "^0.149.0",
-    "@substrat-run/vertical-auth": "^0.24.4"
+    "vitest": "^5.0.5",
+    "@substrat-run/attachment-extractors": "^0.2.12",
+    "@substrat-run/contract-tests": "^0.151.0",
+    "@substrat-run/vertical-auth": "^0.25.0"
   },
   "publishConfig": {
     "access": "public"