@stigmer/server 3.14.0-dev.20260910084630

package/dist/observability/rpc-metrics.js

@@ -0,0 +1,151 @@
+/**
+ * The gRPC request metrics the serving chain records — Java's
+ * `stigmer.grpc.request.count` and `stigmer.grpc.request.duration`
+ * (`GrpcRequestMetricsInterceptor`, cloud `backend/libs/java/grpc/
+ * grpc-request`), names and labels verbatim: `rpc.service` (the
+ * fully-qualified service name), `rpc.method` (the bare method name) and
+ * `rpc.grpc.status_code` (the gRPC status NAME — `OK`, `NOT_FOUND`,
+ * `CANCELLED` with two Ls — never Connect's PascalCase enum key, which the
+ * SigNoz rules would not match). Three consumers read the pair under the
+ * dotted-to-underscored spelling: `telemetry-heartbeat-lost` (the absence
+ * of the count series for ten minutes), `grpc-error-rate-spike` (the
+ * share of `status_code != OK`) and `grpc-latency-regression-p95` (the
+ * duration histogram's buckets), plus the `gRPC RED` dashboard grouped by
+ * every label. Convergence entry 20260909.02.
+ *
+ * This module is library instrumentation, on `@opentelemetry/api` alone:
+ * instruments are created lazily on first use against the GLOBAL meter
+ * provider and are no-ops until a host registers one, so every call site
+ * records unconditionally (the OSS runner's otel-metrics.ts shape; the
+ * cloud composition's registries are its siblings). Lazy creation is what
+ * makes the host's boot order irrelevant — the API has no proxy meter
+ * provider, so an instrument created before registration would stay a
+ * no-op forever. Two facts a host must know:
+ *
+ *   - The counter is BORN AT ZERO by `initRpcMetrics` (Java's constructor
+ *     `add(0)`, the heartbeat's premise, cloud#255): an attribute-less
+ *     series exists from the first post-boot export, so the absence rule's
+ *     ten-minute window measures the export pipeline, not an RPC-free lull
+ *     after a restart. The histogram is deliberately NOT pre-registered —
+ *     a `record(0)` is a real sample that would pollute the percentiles,
+ *     and no rule watches its absence.
+ *   - A host that installs this package from its own `node_modules` runs a
+ *     second copy of `@opentelemetry/api`. The two share one global only
+ *     while this copy's minor version does not exceed the registering
+ *     copy's (`isCompatible`, `internal/semver.ts`); a lockfile bump here
+ *     ahead of the host's makes these instruments silently inert. The
+ *     cloud composition pins the same `^1.9.0` and proves the sharing with
+ *     a composed test on every pin.
+ *
+ * `metricsExportPosture` lets the boot say which of the two states it is
+ * in, so "nothing exported" and "nothing instrumented" stay
+ * distinguishable in the log (the guidelines' explicit-optional-
+ * infrastructure rule).
+ */
+import { Code } from "@connectrpc/connect";
+const METER_NAME = "stigmer-server";
+export const GRPC_STATUS_OK = "OK";
+/**
+ * Connect's error code → the gRPC status name. Connect's `Code` enum has no
+ * OK member (success is the absence of an error), so the table covers the
+ * sixteen error codes and `GRPC_STATUS_OK` names success. Byte-exact
+ * against grpc-java's `Status.Code`; the one spelling trap is CANCELLED.
+ */
+export function grpcStatusName(code) {
+    switch (code) {
+        case Code.Canceled:
+            return "CANCELLED";
+        case Code.Unknown:
+            return "UNKNOWN";
+        case Code.InvalidArgument:
+            return "INVALID_ARGUMENT";
+        case Code.DeadlineExceeded:
+            return "DEADLINE_EXCEEDED";
+        case Code.NotFound:
+            return "NOT_FOUND";
+        case Code.AlreadyExists:
+            return "ALREADY_EXISTS";
+        case Code.PermissionDenied:
+            return "PERMISSION_DENIED";
+        case Code.ResourceExhausted:
+            return "RESOURCE_EXHAUSTED";
+        case Code.FailedPrecondition:
+            return "FAILED_PRECONDITION";
+        case Code.Aborted:
+            return "ABORTED";
+        case Code.OutOfRange:
+            return "OUT_OF_RANGE";
+        case Code.Unimplemented:
+            return "UNIMPLEMENTED";
+        case Code.Internal:
+            return "INTERNAL";
+        case Code.Unavailable:
+            return "UNAVAILABLE";
+        case Code.DataLoss:
+            return "DATA_LOSS";
+        case Code.Unauthenticated:
+            return "UNAUTHENTICATED";
+        default: {
+            const exhaustive = code;
+            throw new Error(`unknown Connect code ${String(exhaustive)}`);
+        }
+    }
+}
+// The PROMISE is memoized (not the result) so concurrent first callers
+// share one creation — two racing registries would double-create every
+// instrument.
+let instrumentsPromise = null;
+export function getRpcInstruments() {
+    instrumentsPromise ??= createInstruments();
+    return instrumentsPromise;
+}
+async function createInstruments() {
+    const api = await import("@opentelemetry/api");
+    const meter = api.metrics.getMeter(METER_NAME);
+    return {
+        requestDuration: meter.createHistogram("stigmer.grpc.request.duration", {
+            unit: "ms",
+            description: "Duration of gRPC server requests in milliseconds",
+        }),
+        requestCount: meter.createCounter("stigmer.grpc.request.count", {
+            description: "Total number of gRPC server requests",
+        }),
+    };
+}
+/**
+ * Fire-and-forget record of one finished RPC — sync so the interceptor
+ * never awaits instrument resolution on the request path. Both
+ * instruments take the same attribute set, Java's single `close` record.
+ */
+export function recordRpc(service, method, status, durationMs) {
+    void getRpcInstruments().then((registry) => {
+        const attributes = {
+            "rpc.service": service,
+            "rpc.method": method,
+            "rpc.grpc.status_code": status,
+        };
+        registry.requestDuration.record(durationMs, attributes);
+        registry.requestCount.add(1, attributes);
+    });
+}
+/**
+ * Births the count series at zero, attribute-less (Java's constructor
+ * posture — no fake `rpc.*` labels on a point that counts nothing).
+ * Awaited by the boot before the port binds so a boot-time provider
+ * exports the series before any traffic.
+ */
+export async function initRpcMetrics() {
+    const registry = await getRpcInstruments();
+    registry.requestCount.add(0);
+}
+export async function metricsExportPosture() {
+    const api = await import("@opentelemetry/api");
+    return api.metrics.getMeter(METER_NAME) === api.createNoopMeter()
+        ? "inert"
+        : "exporting";
+}
+/** Test seam: clears the memoized registry. */
+export function resetRpcInstruments() {
+    instrumentsPromise = null;
+}
+//# sourceMappingURL=rpc-metrics.js.map

package/dist/observability/rpc-metrics.js.map

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

package/dist/pipeline/apiresource-labels.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Well-known stigmer.ai/* metadata labels — ports
+ * backend/libs/go/apiresource/labels.go (itself the Go twin of the cloud
+ * edition's SystemManagedLabels). Keep the three in sync.
+ *
+ * Trust boundary: labels are client-suppliable, so they may be used to
+ * RESTRICT what a request may do (e.g. reject visibility updates on default
+ * instances) but never to GRANT anything. Where a grant-shaped decision is
+ * needed, key it on server-owned state instead (e.g. the parent blueprint's
+ * status.default_instance_id, written only by the create/self-heal flows).
+ * The cloud edition additionally guards the whole reserved namespace at its
+ * write boundaries (GuardReservedLabelsStep); OSS has no such guard, which
+ * is one of the reasons OSS predicates must not trust these labels alone.
+ */
+import type { ApiResourceMetadata } from "@stigmer/protos/ai/stigmer/commons/apiresource/metadata_pb";
+/**
+ * The platform-reserved label key namespace. Keys under this prefix carry
+ * platform semantics (default-agent resolution, personal-environment
+ * uniqueness, default-instance marking) and are written by the server —
+ * never introduced by ordinary client requests on the cloud edition.
+ */
+export declare const RESERVED_LABEL_PREFIX = "stigmer.ai/";
+/**
+ * Marks a blueprint's one auto-created default instance (the empty config
+ * shell the runner resolves when a user has no personal instance). Default
+ * instances carry no visibility of their own: their access always follows
+ * the parent blueprint.
+ */
+export declare const DEFAULT_INSTANCE_LABEL = "stigmer.ai/default-instance";
+/**
+ * Marks a resource whose lifecycle (creation, naming, visibility) is
+ * system-managed; user mutations of the managed aspects are rejected.
+ */
+export declare const SYSTEM_MANAGED_LABEL = "stigmer.ai/system-managed";
+/**
+ * The only value that activates a reserved marker label; any other value is
+ * inert (matching cloud's "true".equals(...)). Stamped by the flows that
+ * create system-managed resources (e.g. the defaultinstance factories) and
+ * read by the predicates here.
+ */
+export declare const RESERVED_LABEL_TRUE = "true";
+/**
+ * Whether the metadata carries the DEFAULT_INSTANCE_LABEL marker
+ * (undefined-safe) — Go IsDefaultInstance.
+ *
+ * Because OSS has no reserved-label write guard, callers making a
+ * restrict-shaped decision should combine this with the authoritative
+ * parent pointer (blueprint status.default_instance_id) — the label alone
+ * misses pre-labeling legacy rows and can be dropped by a client update.
+ */
+export declare function isDefaultInstance(metadata: ApiResourceMetadata | undefined): boolean;
+//# sourceMappingURL=apiresource-labels.d.ts.map

package/dist/pipeline/apiresource-labels.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apiresource-labels.d.ts","sourceRoot":"","sources":["../../src/pipeline/apiresource-labels.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4DAA4D,CAAC;AAEtG;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,gBAAgB,CAAC;AAEnD;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,gCAA6C,CAAC;AAEjF;;;GAGG;AACH,eAAO,MAAM,oBAAoB,8BAA2C,CAAC;AAE7E;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,SAAS,CAAC;AAE1C;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,mBAAmB,GAAG,SAAS,GACxC,OAAO,CAET"}

package/dist/pipeline/apiresource-labels.js

@@ -0,0 +1,39 @@
+/**
+ * The platform-reserved label key namespace. Keys under this prefix carry
+ * platform semantics (default-agent resolution, personal-environment
+ * uniqueness, default-instance marking) and are written by the server —
+ * never introduced by ordinary client requests on the cloud edition.
+ */
+export const RESERVED_LABEL_PREFIX = "stigmer.ai/";
+/**
+ * Marks a blueprint's one auto-created default instance (the empty config
+ * shell the runner resolves when a user has no personal instance). Default
+ * instances carry no visibility of their own: their access always follows
+ * the parent blueprint.
+ */
+export const DEFAULT_INSTANCE_LABEL = `${RESERVED_LABEL_PREFIX}default-instance`;
+/**
+ * Marks a resource whose lifecycle (creation, naming, visibility) is
+ * system-managed; user mutations of the managed aspects are rejected.
+ */
+export const SYSTEM_MANAGED_LABEL = `${RESERVED_LABEL_PREFIX}system-managed`;
+/**
+ * The only value that activates a reserved marker label; any other value is
+ * inert (matching cloud's "true".equals(...)). Stamped by the flows that
+ * create system-managed resources (e.g. the defaultinstance factories) and
+ * read by the predicates here.
+ */
+export const RESERVED_LABEL_TRUE = "true";
+/**
+ * Whether the metadata carries the DEFAULT_INSTANCE_LABEL marker
+ * (undefined-safe) — Go IsDefaultInstance.
+ *
+ * Because OSS has no reserved-label write guard, callers making a
+ * restrict-shaped decision should combine this with the authoritative
+ * parent pointer (blueprint status.default_instance_id) — the label alone
+ * misses pre-labeling legacy rows and can be dropped by a client update.
+ */
+export function isDefaultInstance(metadata) {
+    return metadata?.labels[DEFAULT_INSTANCE_LABEL] === RESERVED_LABEL_TRUE;
+}
+//# sourceMappingURL=apiresource-labels.js.map

package/dist/pipeline/apiresource-labels.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apiresource-labels.js","sourceRoot":"","sources":["../../src/pipeline/apiresource-labels.ts"],"names":[],"mappings":"AAgBA;;;;;GAKG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,aAAa,CAAC;AAEnD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,GAAG,qBAAqB,kBAAkB,CAAC;AAEjF;;;GAGG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,GAAG,qBAAqB,gBAAgB,CAAC;AAE7E;;;;;GAKG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,MAAM,CAAC;AAE1C;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB,CAC/B,QAAyC;IAEzC,OAAO,QAAQ,EAAE,MAAM,CAAC,sBAAsB,CAAC,KAAK,mBAAmB,CAAC;AAC1E,CAAC"}

package/dist/pipeline/apiresource-meta.d.ts

@@ -0,0 +1,35 @@
+import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import type { ApiResourceKindMeta } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+/** Go GetKindMeta: the kind_meta extension of the enum value. */
+export declare function getKindMeta(kind: ApiResourceKind): ApiResourceKindMeta;
+/** Go GetIdPrefix: e.g. agent → "agt". */
+export declare function getIdPrefix(kind: ApiResourceKind): string;
+/** Go GetKindName: the canonical name, e.g. agent → "Agent" (error copy uses this). */
+export declare function getKindName(kind: ApiResourceKind): string;
+/**
+ * Go GetKindEnum: resolve a resource's `kind` string field to the enum via
+ * canonical kind_meta.name matching (case-insensitive, underscores
+ * ignored) — twin of Cloud's ApiResourceKindExtractor.
+ */
+export declare function getKindEnum(kindValue: string): ApiResourceKind;
+/**
+ * Go DefaultVisibilityFor: blueprint kinds flagged defaults_to_org_visibility
+ * get visibility_org (blueprints are shared org assets — a private default
+ * would silently hide new blueprints from teammates); all others get
+ * visibility_private.
+ */
+export declare function defaultVisibilityFor(kind: ApiResourceKind): ApiResourceVisibility;
+/**
+ * Go SupportsVisibility: PRIVATE and UNSPECIFIED are always supported (no
+ * visibility grant); every other level requires the matching supports_*
+ * flag. Kinds with no VisibilityConfig are private-only.
+ */
+export declare function supportsVisibility(kind: ApiResourceKind, visibility: ApiResourceVisibility): boolean;
+/**
+ * Go SupportedVisibilityLevels: comma-joined level names, always starting
+ * with visibility_private — both editions build the same INVALID_ARGUMENT
+ * copy from this exact format.
+ */
+export declare function supportedVisibilityLevels(kind: ApiResourceKind): string;
+//# sourceMappingURL=apiresource-meta.d.ts.map

package/dist/pipeline/apiresource-meta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apiresource-meta.d.ts","sourceRoot":"","sources":["../../src/pipeline/apiresource-meta.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,qBAAqB,EAAE,MAAM,wDAAwD,CAAC;AAC/F,OAAO,EACL,eAAe,EAGhB,MAAM,qFAAqF,CAAC;AAC7F,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qFAAqF,CAAC;AAE/H,iEAAiE;AACjE,wBAAgB,WAAW,CAAC,IAAI,EAAE,eAAe,GAAG,mBAAmB,CAMtE;AAED,0CAA0C;AAC1C,wBAAgB,WAAW,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,CAEzD;AAED,uFAAuF;AACvF,wBAAgB,WAAW,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,CAEzD;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,eAAe,CAS9D;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,eAAe,GAAG,qBAAqB,CAKjF;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,eAAe,EACrB,UAAU,EAAE,qBAAqB,GAChC,OAAO,CAYT;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,CAavE"}

package/dist/pipeline/apiresource-meta.js

@@ -0,0 +1,114 @@
+/**
+ * Kind-metadata helpers — port backend/libs/go/apiresource/metadata.go.
+ * The proto `kind_meta` enum-value extension is the single source of truth
+ * for a kind's canonical name, id prefix, and visibility config; deriving
+ * anything from enum spellings is forbidden (Go learned this at
+ * stigmer/stigmer#545 — PascalCase cannot recover "oauth_app").
+ *
+ * Both editions resolve the same strings from the same proto metadata; the
+ * visibility helpers mirror Cloud's VisibilityConfigResolver so the
+ * cross-edition error contract is identical by construction.
+ */
+import { getOption, hasOption } from "@bufbuild/protobuf";
+import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
+import { ApiResourceKindSchema, kind_meta, } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+/** Go GetKindMeta: the kind_meta extension of the enum value. */
+export function getKindMeta(kind) {
+    const valueDesc = kindValueDescriptor(kind);
+    if (valueDesc === undefined || !hasOption(valueDesc, kind_meta)) {
+        throw new Error(`kind_meta extension not found for kind: ${kind}`);
+    }
+    return getOption(valueDesc, kind_meta);
+}
+/** Go GetIdPrefix: e.g. agent → "agt". */
+export function getIdPrefix(kind) {
+    return getKindMeta(kind).idPrefix;
+}
+/** Go GetKindName: the canonical name, e.g. agent → "Agent" (error copy uses this). */
+export function getKindName(kind) {
+    return getKindMeta(kind).name;
+}
+/**
+ * Go GetKindEnum: resolve a resource's `kind` string field to the enum via
+ * canonical kind_meta.name matching (case-insensitive, underscores
+ * ignored) — twin of Cloud's ApiResourceKindExtractor.
+ */
+export function getKindEnum(kindValue) {
+    if (kindValue === "") {
+        throw new Error("kind field is empty");
+    }
+    const kind = kindsByCanonicalName().get(canonicalKindName(kindValue));
+    if (kind === undefined) {
+        throw new Error(`unknown kind: ${kindValue}`);
+    }
+    return kind;
+}
+/**
+ * Go DefaultVisibilityFor: blueprint kinds flagged defaults_to_org_visibility
+ * get visibility_org (blueprints are shared org assets — a private default
+ * would silently hide new blueprints from teammates); all others get
+ * visibility_private.
+ */
+export function defaultVisibilityFor(kind) {
+    const config = getKindMeta(kind).authorization?.visibility;
+    return config?.defaultsToOrgVisibility === true
+        ? ApiResourceVisibility.visibility_org
+        : ApiResourceVisibility.visibility_private;
+}
+/**
+ * Go SupportsVisibility: PRIVATE and UNSPECIFIED are always supported (no
+ * visibility grant); every other level requires the matching supports_*
+ * flag. Kinds with no VisibilityConfig are private-only.
+ */
+export function supportsVisibility(kind, visibility) {
+    const config = getKindMeta(kind).authorization?.visibility;
+    switch (visibility) {
+        case ApiResourceVisibility.visibility_public:
+            return config?.supportsPublic === true;
+        case ApiResourceVisibility.visibility_org:
+            return config?.supportsOrg === true;
+        case ApiResourceVisibility.visibility_platform:
+            return config?.supportsPlatform === true;
+        default:
+            return true;
+    }
+}
+/**
+ * Go SupportedVisibilityLevels: comma-joined level names, always starting
+ * with visibility_private — both editions build the same INVALID_ARGUMENT
+ * copy from this exact format.
+ */
+export function supportedVisibilityLevels(kind) {
+    const config = getKindMeta(kind).authorization?.visibility;
+    let levels = "visibility_private";
+    if (config?.supportsOrg === true) {
+        levels += ", visibility_org";
+    }
+    if (config?.supportsPublic === true) {
+        levels += ", visibility_public";
+    }
+    if (config?.supportsPlatform === true) {
+        levels += ", visibility_platform";
+    }
+    return levels;
+}
+function kindValueDescriptor(kind) {
+    return ApiResourceKindSchema.values.find((value) => value.number === kind);
+}
+/** Canonical spelling: lowercase, underscores stripped (Go canonicalKindName). */
+function canonicalKindName(value) {
+    return value.toLowerCase().replaceAll("_", "");
+}
+let canonicalNameCache;
+function kindsByCanonicalName() {
+    if (canonicalNameCache === undefined) {
+        canonicalNameCache = new Map(ApiResourceKindSchema.values
+            .filter((value) => hasOption(value, kind_meta))
+            .map((value) => [
+            canonicalKindName(getOption(value, kind_meta).name),
+            value.number,
+        ]));
+    }
+    return canonicalNameCache;
+}
+//# sourceMappingURL=apiresource-meta.js.map

package/dist/pipeline/apiresource-meta.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apiresource-meta.js","sourceRoot":"","sources":["../../src/pipeline/apiresource-meta.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAG1D,OAAO,EAAE,qBAAqB,EAAE,MAAM,wDAAwD,CAAC;AAC/F,OAAO,EAEL,qBAAqB,EACrB,SAAS,GACV,MAAM,qFAAqF,CAAC;AAG7F,iEAAiE;AACjE,MAAM,UAAU,WAAW,CAAC,IAAqB;IAC/C,MAAM,SAAS,GAAG,mBAAmB,CAAC,IAAI,CAAC,CAAC;IAC5C,IAAI,SAAS,KAAK,SAAS,IAAI,CAAC,SAAS,CAAC,SAAS,EAAE,SAAS,CAAC,EAAE,CAAC;QAChE,MAAM,IAAI,KAAK,CAAC,2CAA2C,IAAI,EAAE,CAAC,CAAC;IACrE,CAAC;IACD,OAAO,SAAS,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;AACzC,CAAC;AAED,0CAA0C;AAC1C,MAAM,UAAU,WAAW,CAAC,IAAqB;IAC/C,OAAO,WAAW,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC;AACpC,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,WAAW,CAAC,IAAqB;IAC/C,OAAO,WAAW,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC;AAChC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,SAAiB;IAC3C,IAAI,SAAS,KAAK,EAAE,EAAE,CAAC;QACrB,MAAM,IAAI,KAAK,CAAC,qBAAqB,CAAC,CAAC;IACzC,CAAC;IACD,MAAM,IAAI,GAAG,oBAAoB,EAAE,CAAC,GAAG,CAAC,iBAAiB,CAAC,SAAS,CAAC,CAAC,CAAC;IACtE,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CAAC,iBAAiB,SAAS,EAAE,CAAC,CAAC;IAChD,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAqB;IACxD,MAAM,MAAM,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC,aAAa,EAAE,UAAU,CAAC;IAC3D,OAAO,MAAM,EAAE,uBAAuB,KAAK,IAAI;QAC7C,CAAC,CAAC,qBAAqB,CAAC,cAAc;QACtC,CAAC,CAAC,qBAAqB,CAAC,kBAAkB,CAAC;AAC/C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAChC,IAAqB,EACrB,UAAiC;IAEjC,MAAM,MAAM,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC,aAAa,EAAE,UAAU,CAAC;IAC3D,QAAQ,UAAU,EAAE,CAAC;QACnB,KAAK,qBAAqB,CAAC,iBAAiB;YAC1C,OAAO,MAAM,EAAE,cAAc,KAAK,IAAI,CAAC;QACzC,KAAK,qBAAqB,CAAC,cAAc;YACvC,OAAO,MAAM,EAAE,WAAW,KAAK,IAAI,CAAC;QACtC,KAAK,qBAAqB,CAAC,mBAAmB;YAC5C,OAAO,MAAM,EAAE,gBAAgB,KAAK,IAAI,CAAC;QAC3C;YACE,OAAO,IAAI,CAAC;IAChB,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,yBAAyB,CAAC,IAAqB;IAC7D,MAAM,MAAM,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC,aAAa,EAAE,UAAU,CAAC;IAC3D,IAAI,MAAM,GAAG,oBAAoB,CAAC;IAClC,IAAI,MAAM,EAAE,WAAW,KAAK,IAAI,EAAE,CAAC;QACjC,MAAM,IAAI,kBAAkB,CAAC;IAC/B,CAAC;IACD,IAAI,MAAM,EAAE,cAAc,KAAK,IAAI,EAAE,CAAC;QACpC,MAAM,IAAI,qBAAqB,CAAC;IAClC,CAAC;IACD,IAAI,MAAM,EAAE,gBAAgB,KAAK,IAAI,EAAE,CAAC;QACtC,MAAM,IAAI,uBAAuB,CAAC;IACpC,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,mBAAmB,CAAC,IAAqB;IAChD,OAAO,qBAAqB,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,KAAK,IAAI,CAAC,CAAC;AAC7E,CAAC;AAED,kFAAkF;AAClF,SAAS,iBAAiB,CAAC,KAAa;IACtC,OAAO,KAAK,CAAC,WAAW,EAAE,CAAC,UAAU,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;AACjD,CAAC;AAED,IAAI,kBAA4D,CAAC;AAEjE,SAAS,oBAAoB;IAC3B,IAAI,kBAAkB,KAAK,SAAS,EAAE,CAAC;QACrC,kBAAkB,GAAG,IAAI,GAAG,CAC1B,qBAAqB,CAAC,MAAM;aACzB,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,SAAS,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;aAC9C,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC;YACd,iBAAiB,CAAC,SAAS,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC,IAAI,CAAC;YACnD,KAAK,CAAC,MAAyB;SAChC,CAAC,CACL,CAAC;IACJ,CAAC;IACD,OAAO,kBAAkB,CAAC;AAC5B,CAAC"}

package/dist/pipeline/chain.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The server's interceptor chain, in the ratified order (D2 §2; position
+ * 0 added by 20260830.03, gate ruling Q1; the request-metrics position
+ * added by 20260909.02, gate ruling Q1):
+ *
+ *   0. error boundary   — SERVING chain only
+ *                         (interceptors/error-boundary.ts: the raw-error
+ *                         conversion net + the visitor sanitizer seam)
+ *   1. identity source  — REQUIRED parameter (DD-004; O2)
+ *      request metrics  — SERVING chain only, immediately inside the
+ *                         identity source (interceptors/request-metrics.ts:
+ *                         Java's RED emitter at Java's position — an
+ *                         identity refusal is position 1's own record,
+ *                         never a counted error)
+ *   2. logging          — level-tiered per outcome
+ *   3. protovalidate    — boundary validation before any handler
+ *   4. apiresource      — kind context from the service option
+ *
+ * ConnectRPC applies array order as nesting order (first = outermost),
+ * verified by spike SP-B. Positions 2–4 are the SAME for external
+ * transports and in-process router-transport calls — validation parity is
+ * the point. Position 1 deliberately differs per transport (O2, ruling
+ * Q4): the serving chain runs the verifier chassis over the wire's
+ * credentials, the in-process chain stamps the internal caller class its
+ * own interceptor mints (interceptors/auth.ts owns both sources and the
+ * spoofing-impossible invariant). The parameter is required — a chain
+ * without an identity source is a compile error, never a silently
+ * unauthenticated transport.
+ *
+ * The two serving-only interceptors travel as ONE optional parameter so
+ * a chain cannot half-inherit them: in-process hops are exempt from
+ * sanitization by construction — the outer handler needs the full inner
+ * diagnostic (the Java InProcessCallContextHolder exemption,
+ * structurally) — and an in-process hop is not a request, so it is not
+ * counted as one.
+ */
+import type { Interceptor } from "@connectrpc/connect";
+import type { Logger } from "../boot/logger.js";
+/** The interceptors only the serving chain composes; the in-process chain passes none. */
+export interface ServingChainInterceptors {
+    readonly errorBoundary: Interceptor;
+    readonly requestMetrics: Interceptor;
+}
+export declare function buildInterceptorChain(logger: Logger, identitySource: Interceptor, serving?: ServingChainInterceptors): Interceptor[];
+//# sourceMappingURL=chain.d.ts.map

package/dist/pipeline/chain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chain.d.ts","sourceRoot":"","sources":["../../src/pipeline/chain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEvD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAKhD,0FAA0F;AAC1F,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,aAAa,EAAE,WAAW,CAAC;IACpC,QAAQ,CAAC,cAAc,EAAE,WAAW,CAAC;CACtC;AAED,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,WAAW,EAC3B,OAAO,CAAC,EAAE,wBAAwB,GACjC,WAAW,EAAE,CASf"}

package/dist/pipeline/chain.js

@@ -0,0 +1,14 @@
+import { createApiResourceInterceptor } from "./interceptors/apiresource.js";
+import { createLoggingInterceptor } from "./interceptors/logging.js";
+import { createProtovalidateInterceptor } from "./interceptors/protovalidate.js";
+export function buildInterceptorChain(logger, identitySource, serving) {
+    return [
+        ...(serving === undefined ? [] : [serving.errorBoundary]),
+        identitySource,
+        ...(serving === undefined ? [] : [serving.requestMetrics]),
+        createLoggingInterceptor(logger),
+        createProtovalidateInterceptor(),
+        createApiResourceInterceptor(),
+    ];
+}
+//# sourceMappingURL=chain.js.map

package/dist/pipeline/chain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chain.js","sourceRoot":"","sources":["../../src/pipeline/chain.ts"],"names":[],"mappings":"AAuCA,OAAO,EAAE,4BAA4B,EAAE,MAAM,+BAA+B,CAAC;AAC7E,OAAO,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AACrE,OAAO,EAAE,8BAA8B,EAAE,MAAM,iCAAiC,CAAC;AAQjF,MAAM,UAAU,qBAAqB,CACnC,MAAc,EACd,cAA2B,EAC3B,OAAkC;IAElC,OAAO;QACL,GAAG,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC;QACzD,cAAc;QACd,GAAG,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC;QAC1D,wBAAwB,CAAC,MAAM,CAAC;QAChC,8BAA8B,EAAE;QAChC,4BAA4B,EAAE;KAC/B,CAAC;AACJ,CAAC"}

package/dist/pipeline/errors.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Domain error constructors — port backend/libs/go/grpc/server.go's helper
+ * family. Errors are API surface (guidelines §8): the CLI, console, and SDK
+ * show these messages verbatim, so the FORMAT STRINGS are byte-pinned
+ * contract, mirrored character-for-character from Go.
+ *
+ * The sanitization contract (stigmer/stigmer#478): internalError's
+ * wire-visible description is ONLY the static message — the cause's raw
+ * text can carry storage-engine detail or filesystem paths, and on an
+ * anonymous surface that is information disclosure. The cause rides
+ * ConnectError.cause for server-side logs; it never crosses the wire.
+ */
+import { Code, ConnectError } from "@connectrpc/connect";
+/** Go NotFoundError: "%s not found: %s". */
+export declare function notFoundError(resource: string, id: string): ConnectError;
+/** Go InvalidArgumentError (callers pre-format their message). */
+export declare function invalidArgumentError(message: string): ConnectError;
+/** Go AlreadyExistsError: "%s already exists: %s". */
+export declare function alreadyExistsError(resource: string, id: string): ConnectError;
+/**
+ * Go FailedPreconditionError — the system is not in a state required for
+ * the operation (vs AlreadyExists, which tells the caller to stop).
+ */
+export declare function failedPreconditionError(message: string): ConnectError;
+/** Go AbortedError — retryable conflict (e.g. an in-flight dedupe claim). */
+export declare function abortedError(message: string): ConnectError;
+/** Go UnavailableError — a dependency is temporarily unreachable. */
+export declare function unavailableError(message: string): ConnectError;
+/**
+ * Go InternalError: the wire carries ONLY `message`; `cause` stays
+ * server-side (#478). Callers keep writing
+ * internalError(err, "failed to <do thing>") exactly as in Go — the split
+ * between operator-visible detail and client-visible copy happens here.
+ */
+export declare function internalError(cause: unknown, message: string): ConnectError;
+/**
+ * grpc-go's codes.Code.String() name for a connect Code — for surfaces
+ * that persist the code NAME rather than raise it (McpServer
+ * connect_status.failure_code copies the blocking RPC's classification in
+ * CamelCase form per status.proto's field doc).
+ */
+export declare function grpcCodeName(code: Code): string;
+/**
+ * Reproduces the wire message grpc-go's status.FromError manufactures for
+ * %w-wrapped status errors: when Go wraps a downstream in-process client
+ * error with fmt.Errorf("%s: %w", ...), PipelineError.GRPCStatus's
+ * errors.As branch keeps the INNER code but rewrites the message to the
+ * full wrapped text — and the inner client error's Error() renders as
+ * `rpc error: code = <CodeName> desc = <message>`. Byte-parity with Go on
+ * the two arms that hit this (agent create's CreateDefaultInstance,
+ * session create's ResolveDefaultAgentInstance). The transport-formatting
+ * leak is filed as stigmer/stigmer#852 for a both-editions post-cutover
+ * fix; until then this shim IS the wire contract.
+ *
+ * rawMessage is the code-prefix-free message — ConnectError.message
+ * prepends "[code_name] ", which must not ride the manufactured desc.
+ */
+export declare function goWrappedStatusError(prefix: string, error: ConnectError): ConnectError;
+/**
+ * The `%v` rendering of a grpc-go status error — `rpc error: code = <Name>
+ * desc = <message>` — for sites that embed a downstream error's text under
+ * a DIFFERENT outer code (e.g. workflowexecution's approval forwarding
+ * flattens the child's status to Unavailable but Go's %v still prints the
+ * inner wire text). goWrappedStatusError above is the %w twin that also
+ * keeps the inner code.
+ */
+export declare function goGrpcErrorText(error: ConnectError): string;
+/**
+ * Re-throws a downstream in-process client error UNWRAPPED — Go's
+ * `return err // already a gRPC error from the client` arms, where the
+ * inner status reaches the wire verbatim (no prefix, no manufactured
+ * desc).
+ *
+ * A FRESH ConnectError is constructed on purpose: the router-transport
+ * client's error instance carries the INNER response's metadata, and
+ * serializing that metadata into the outer response's trailers produces
+ * malformed HTTP/2 (the client surfaces NGHTTP2_PROTOCOL_ERROR instead of
+ * the status — found by the local-execution roster on agent-execution
+ * create's unknown-agent arm, which is unreachable while the engine gate
+ * refuses first). Same code, same rawMessage, no inherited metadata.
+ */
+export declare function rethrownStatusError(error: ConnectError): ConnectError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/pipeline/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/pipeline/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEzD,4CAA4C;AAC5C,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,YAAY,CAExE;AAED,kEAAkE;AAClE,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,CAElE;AAED,sDAAsD;AACtD,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,YAAY,CAE7E;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,CAErE;AAED,6EAA6E;AAC7E,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,CAE1D;AAED,qEAAqE;AACrE,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,CAE9D;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,YAAY,CAE3E;AA2BD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAE/C;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,YAAY,GAClB,YAAY,CAKd;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CAE3D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,YAAY,GAAG,YAAY,CAErE"}