@substrat-run/control-plane-api 0.110.0 → 0.112.0

package/dist/api.d.ts

@@ -6,7 +6,7 @@ import type { PlatformActorAuth, BuilderAuth, Principal } from './auth.js';
 import { type VerticalClient } from './vertical-client.js';
 import type { DeployVerticalFn, FetchVerticalAssetFn, FetchVerticalModulesFn } from './deploy.js';
 import type { PatchScriptBindingsFn } from './wfp.js';
-import type { ObservabilityReader } from './observability.js';
+import { type ObservabilityReader } from './observability.js';
 import type { PlatformRuntime } from './platform-runtime.js';
 import { type DoNamespaceReader } from './do-namespaces.js';
 import type { DirectoryBackupStore, ScopeBackupStore } from './backups.js';
@@ -308,6 +308,10 @@ export declare const denialLogQuery: z.ZodObject<{
     since: z.ZodOptional<z.ZodString>;
     until: z.ZodOptional<z.ZodString>;
     limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    groupBy: z.ZodOptional<z.ZodEnum<{
+        "actor-permission": "actor-permission";
+        operation: "operation";
+    }>>;
 }, z.core.$strip>;
 export declare const DEFAULT_MODEL_MARGIN_PERCENT = 20;
 /**

package/dist/api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAE5B,OAAO,EAmDL,CAAC,EAGF,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EACV,UAAU,EACV,kBAAkB,EAClB,wBAAwB,EACxB,oBAAoB,EACpB,eAAe,EAGf,eAAe,EAOhB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAmB,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAIvE,OAAO,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAC3E,OAAO,EAA4B,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAmBrF,OAAO,KAAK,EAEV,gBAAgB,EAChB,oBAAoB,EACpB,sBAAsB,EACvB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAyBtD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,EAAuB,KAAK,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACjF,OAAO,KAAK,EAEV,oBAAoB,EAEpB,gBAAgB,EACjB,MAAM,cAAc,CAAC;AAEtB,OAAO,EAGL,KAAK,yBAAyB,EAC/B,MAAM,uBAAuB,CAAC;AAE/B;;;;;;;;;;GAUG;AACH,MAAM,WAAW,mBAAmB;IAClC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,EAAE,UAAU,EAAE,UAAU,KAAK,OAAO,CAAC,eAAe,CAAC,CAAC;IAC9E,QAAQ,CAAC,EAAE,CACT,IAAI,EAAE,SAAS,EACf,UAAU,EAAE,UAAU,EACtB,IAAI,EAAE;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,wBAAwB,CAAA;KAAE,KACtD,OAAO,CAAC,kBAAkB,CAAC,CAAC;IACjC;;;;;OAKG;IACH,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,EAAE,UAAU,EAAE,UAAU,KAAK,OAAO,CAAC,oBAAoB,CAAC,CAAC;IACxF;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,OAAO,CAAC,eAAe,CAAC,CAAC;CAC/E;AAED,MAAM,WAAW,sBAAsB;IACrC;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,IAAI,EAAE,SAAS,CAAC;IAChB;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAC3C;;;;;;;;OAQG;IACH,eAAe,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC,CAAC;IAC9D;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,KAAK,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAAC;IAChG;;;;;;;;;OASG;IACH,sBAAsB,CAAC,EAAE,CACvB,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,eAAe,KACnB,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAAC;IACzC;;;;;;;OAOG;IACH,kBAAkB,CAAC,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAAC;IACpF;;;;;OAKG;IACH,cAAc,CAAC,EAAE,gBAAgB,CAAC;IAClC;;;;;OAKG;IACH,oBAAoB,CAAC,EAAE,sBAAsB,CAAC;IAC9C;;;;;;;;;;OAUG;IACH,kBAAkB,CAAC,EAAE,oBAAoB,CAAC;IAC1C;;;;;;OAMG;IACH,mBAAmB,CAAC,EAAE,qBAAqB,CAAC;IAC5C;;;;;;;;OAQG;IACH,sBAAsB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C;;;;OAIG;IACH,YAAY,EAAE,iBAAiB,CAAC;IAChC;;;;;;OAMG;IACH,mBAAmB,CAAC,EAAE,WAAW,CAAC;IAClC;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;;;;;OASG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;;;;OAQG;IACH,aAAa,CAAC,EAAE,mBAAmB,CAAC;IACpC;;;;;;;;;;;;OAYG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;IAC3D;;;;;;;;;OASG;IACH,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC;;;;;OAKG;IACH,YAAY,CAAC,EAAE,iBAAiB,CAAC;IACjC;;;;;;;;;;;;;OAaG;IACH,YAAY,CAAC,EAAE,gBAAgB,CAAC;IAChC;;;;;;;;;OASG;IACH,gBAAgB,CAAC,EAAE,oBAAoB,CAAC;IACxC;;;;;;;OAOG;IACH,iBAAiB,CAAC,EAAE,yBAAyB,CAAC;IAC9C;;;;;;OAMG;IACH,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC/B;;;;;;;;;;;OAWG;IACH,WAAW,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC/D;AAED;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,+BAA+B,CAAC;AACnE,eAAO,MAAM,yBAAyB,kCAAkC,CAAC;AAKzE,KAAK,IAAI,GAAG;IAAE,KAAK,EAAE,eAAe,CAAC;IAAC,SAAS,EAAE,SAAS,CAAA;CAAE,CAAC;AA0O7D;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,cAAc;;;;;;;iBAOzB,CAAC;AA+FH,eAAO,MAAM,4BAA4B,KAAK,CAAC;AAM/C;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,sBAAsB,GAAG,IAAI,CAAC;IAAE,SAAS,EAAE,IAAI,CAAA;CAAE,CAAC,CAm7IhG"}
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"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"}

package/dist/api.js

@@ -1,5 +1,5 @@
 import { Hono } from 'hono';
-import { parseHostname, withLabel, RESERVED_LABEL_SEPARATOR, adminAction, ASSET_PART_PREFIX, assetHash, channelName, connectionActivity, connectionActivitySource, connectionCredential, connectionFilter, connectionProbe, createTenantInput, entitlementGrantInput, hostname as hostnameSchema, hostnameRegion, hostnameStatus, identityLink, errorCode, issueStatus, issueStatusInput, listPageQuery, matchesOutboundHost, pageOf, platformRequestFilter, principalId as principalIdSchema, promotionAcknowledgement, provisionableJurisdiction, publishVersionInput, queryScopeInput, readScopeTableInput, entityHistoryInput, eventFacetInput, createOrgInput, roleKey as roleKeySchema, DEFAULT_DENIAL_LIMIT, DENIAL_LIMIT_MAX, registerVerticalInput, serviceDimensions, sweepRunKind, sweepRunOutcome, scopeDump, dataSubjectId as dataSubjectIdSchema, scopeId as scopeIdSchema, scopeStatus, storageShape, surfaceName, tenantId as tenantIdSchema, tenantStatus, versionOrigin, z, PROBLEM_CONTENT_TYPE, toProblem, } from '@substrat-run/contracts';
+import { parseHostname, withLabel, RESERVED_LABEL_SEPARATOR, adminAction, ASSET_PART_PREFIX, assetHash, channelName, connectionActivity, connectionActivitySource, connectionCredential, connectionFilter, connectionProbe, createTenantInput, entitlementGrantInput, hostname as hostnameSchema, hostnameRegion, hostnameStatus, identityLink, errorCode, issueStatus, issueStatusInput, listPageQuery, matchesOutboundHost, pageOf, platformRequestFilter, principalId as principalIdSchema, promotionAcknowledgement, provisionableJurisdiction, publishVersionInput, queryScopeInput, readScopeTableInput, entityHistoryInput, eventFacetInput, eventCauseInput, eventEffectsInput, delegatedReadParams, createOrgInput, roleKey as roleKeySchema, DEFAULT_DENIAL_LIMIT, DENIAL_LIMIT_MAX, denialGroupBy, registerVerticalInput, serviceDimensions, sweepRunKind, sweepRunOutcome, scopeDump, dataSubjectId as dataSubjectIdSchema, scopeId as scopeIdSchema, scopeStatus, storageShape, surfaceName, tenantId as tenantIdSchema, tenantStatus, versionOrigin, z, PROBLEM_CONTENT_TYPE, toProblem, } from '@substrat-run/contracts';
 import { attributeFailure } from './failure-attribution.js';
 import { migrationProgress, ulid } from '@substrat-run/kernel';
 import { TENANT_HEADER } from './auth.js';
@@ -28,6 +28,7 @@ function problem(c, answer) {
 }
 import { backfillDeclaredStores, blobStoreBindings, collectBlobStoreHandles, collectTenantStoreHandles, missingStoresForTenant, tenantStoreBindings, } from './tenant-stores.js';
 import { mintPushToken, pushActorFor } from './push-token.js';
+import { TENANT_SERIES_SCOPE_CAP } from './observability.js';
 import { namespacesForScript } from './do-namespaces.js';
 import { backupDirectoryIfDue } from './directory-backup.js';
 import { isCustomHostname, validateBindableHostname, } from './custom-hostnames.js';
@@ -263,6 +264,8 @@ export const denialLogQuery = z.object({
     since: z.string().optional(),
     until: z.string().optional(),
     limit: z.coerce.number().int().min(1).max(DENIAL_LIMIT_MAX).default(DEFAULT_DENIAL_LIMIT),
+    // Which bucketing the summary answers with (#1456); the row read ignores it.
+    groupBy: denialGroupBy.optional(),
 });
 const opsFailuresQuery = z.object({
     tenantId: tenantIdSchema.optional(),
@@ -504,6 +507,7 @@ export function createControlPlaneApi(options) {
         // there is no fleet-wide answer for a forgotten filter to fall back to. Narrowed in
         // the handler by the forced-filter pattern; the allowlist alone is not authz.
         { method: 'GET', re: /\/observability\/tenant-metrics$/ },
+        { method: 'GET', re: /\/observability\/tenant-metrics-series$/ },
         { method: 'GET', re: /\/observability\/tenant-logs$/ },
     ];
     app.use('*', async (c, next) => {
@@ -1279,10 +1283,10 @@ export function createControlPlaneApi(options) {
         const scope = await admin.getScopeRecord(c.get('actor'), tenantId, scopeId);
         if (!scope)
             return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
-        const vertical = await verticalForScope(c, scope);
-        return c.json(vertical
-            ? await vertical.listScopeTables(scopeId)
-            : await admin.listScopeTables(c.get('actor'), tenantId, scopeId));
+        return c.json(await delegatedRead(c, tenantId, scopeId, scope, 'listScopeTables', null, {
+            viaVertical: (v) => v.listScopeTables(scopeId),
+            colocated: () => admin.listScopeTables(c.get('actor'), tenantId, scopeId),
+        }, (r) => r.length));
     });
     // Scope health (#321, criterion #3). The silent failure the field report chased was an
     // ACTIVE scope serving traffic from a DO whose `_substrat_roles` projection is EMPTY:
@@ -1313,10 +1317,12 @@ export function createControlPlaneApi(options) {
         const scope = await admin.getScopeRecord(c.get('actor'), tenantId, scopeId);
         if (!scope)
             return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
-        const vertical = await verticalForScope(c, scope);
-        const tables = vertical
-            ? await vertical.listScopeTables(scopeId)
-            : await admin.listScopeTables(c.get('actor'), tenantId, scopeId);
+        // Health reads the scope the same way the Data view does, so it leaves the same
+        // row: an auditor should not be able to tell which route reached the tables.
+        const tables = await delegatedRead(c, tenantId, scopeId, scope, 'listScopeTables', null, {
+            viaVertical: (v) => v.listScopeTables(scopeId),
+            colocated: () => admin.listScopeTables(c.get('actor'), tenantId, scopeId),
+        }, (r) => r.length);
         const roles = tables.find((t) => t.name === '_substrat_roles');
         const roleCount = roles ? roles.rowCount : null;
         const roleProjectionEmpty = scope.status === 'active' && roleCount === 0;
@@ -1551,10 +1557,91 @@ export function createControlPlaneApi(options) {
         const scope = await admin.getScopeRecord(c.get('actor'), tenantId, scopeId);
         if (!scope)
             return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
+        return c.json(await delegatedRead(c, tenantId, scopeId, scope, 'facetEvents', input, {
+            viaVertical: (v) => v.facetEvents(scopeId, input),
+            colocated: () => admin.facetEvents(c.get('actor'), tenantId, scopeId, input),
+        }, 
+        // The buckets RETURNED, not `total`: the row says how much this read handed
+        // back, and a capped facet hands back fewer than it counted.
+        (r) => r.buckets.length));
+    });
+    /**
+     * Serve a scope read from whichever side holds the data, and leave ONE K-24 row
+     * either way (#1357).
+     *
+     * Every scope-addressed read runs the same ladder — resolve the scope record, ask the
+     * vertical when one resolves, the co-located host otherwise — and only the second
+     * branch reaches `HostAdmin`, where `recordAccess` lives. So on the production path,
+     * which is every hosted vertical, the access log held a `getScopeRecord` entry and
+     * nothing saying what was read: a summary page, a table walk and one record's history
+     * were indistinguishable, and the history page is the one carrying payloads.
+     *
+     * `count` exists because the row records how much came back and every answer counts
+     * differently — a page has `entries`, a facet has `buckets`, a chain has its own
+     * length. Handing each site its own counter keeps that honest rather than logging a
+     * zero everywhere the shape is not a list.
+     *
+     * The record is written AFTER the read succeeds and is not caught: a failed write
+     * fails the request. That is the co-located branch's existing trade, where
+     * `recordAccess` is awaited inside the read — and returning rows whose disclosure went
+     * unrecorded is the thing K-24 exists to prevent.
+     *
+     * `input` is the ROUTE's input, and what the row carries is `delegatedReadParams`'s
+     * projection of it — never the input itself. The co-located branch logs a chosen
+     * subset per method (the entity, not the page; the event, not the walk's depth), and
+     * a row that carried the whole input on this branch alone would tell an auditor which
+     * branch served the request. The projection lives in contracts so it is one
+     * definition; the test drives every method both ways and compares the rows.
+     */
+    async function delegatedRead(c, tenantId, scopeId, scope, method, input, run, count) {
         const vertical = await verticalForScope(c, scope);
-        return c.json(vertical
-            ? await vertical.facetEvents(scopeId, input)
-            : await admin.facetEvents(c.get('actor'), tenantId, scopeId, input));
+        // The co-located branch already records inside the read — adding a row here would
+        // log it twice, which is a different kind of dishonest log.
+        if (!vertical)
+            return run.colocated();
+        const answer = await run.viaVertical(vertical);
+        await admin.recordDelegatedRead(c.get('actor'), {
+            method,
+            tenantId,
+            scopeId,
+            params: delegatedReadParams[method](input),
+            resultCount: count(answer),
+        });
+        return answer;
+    }
+    // #1237: one event's causal chain, walked backwards. Delegated exactly like the
+    // history read below — through the vertical holding the scope's data when one
+    // resolves, the co-located host otherwise.
+    app.get('/tenants/:tenantId/scopes/:scopeId/cause', async (c) => {
+        const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
+        const scopeId = scopeIdSchema.parse(c.req.param('scopeId'));
+        const input = eventCauseInput.parse({
+            eventId: c.req.query('eventId'),
+            maxDepth: c.req.query('maxDepth') ? Number(c.req.query('maxDepth')) : undefined,
+        });
+        const scope = await admin.getScopeRecord(c.get('actor'), tenantId, scopeId);
+        if (!scope)
+            return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
+        return c.json(await delegatedRead(c, tenantId, scopeId, scope, 'eventCause', input, {
+            viaVertical: (v) => v.eventCause(scopeId, input),
+            colocated: () => admin.eventCause(c.get('actor'), tenantId, scopeId, input),
+        }, (r) => r.chain.length));
+    });
+    // #1237 forward: what one event set off. Delegated like its backwards twin.
+    app.get('/tenants/:tenantId/scopes/:scopeId/effects', async (c) => {
+        const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
+        const scopeId = scopeIdSchema.parse(c.req.param('scopeId'));
+        const input = eventEffectsInput.parse({
+            eventId: c.req.query('eventId'),
+            maxNodes: c.req.query('maxNodes') ? Number(c.req.query('maxNodes')) : undefined,
+        });
+        const scope = await admin.getScopeRecord(c.get('actor'), tenantId, scopeId);
+        if (!scope)
+            return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
+        return c.json(await delegatedRead(c, tenantId, scopeId, scope, 'eventEffects', input, {
+            viaVertical: (v) => v.eventEffects(scopeId, input),
+            colocated: () => admin.eventEffects(c.get('actor'), tenantId, scopeId, input),
+        }, (r) => r.count));
     });
     // #1235: one record's event history — the per-entity pivot of the audit spine.
     // Delegated exactly like the table reads: through the vertical that holds the
@@ -1571,10 +1658,10 @@ export function createControlPlaneApi(options) {
         const scope = await admin.getScopeRecord(c.get('actor'), tenantId, scopeId);
         if (!scope)
             return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
-        const vertical = await verticalForScope(c, scope);
-        return c.json(vertical
-            ? await vertical.entityHistory(scopeId, input)
-            : await admin.entityHistory(c.get('actor'), tenantId, scopeId, input));
+        return c.json(await delegatedRead(c, tenantId, scopeId, scope, 'entityHistory', input, {
+            viaVertical: (v) => v.entityHistory(scopeId, input),
+            colocated: () => admin.entityHistory(c.get('actor'), tenantId, scopeId, input),
+        }, (r) => r.entries.length));
     });
     app.get('/tenants/:tenantId/scopes/:scopeId/tables/:table', async (c) => {
         const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
@@ -1587,10 +1674,10 @@ export function createControlPlaneApi(options) {
         const scope = await admin.getScopeRecord(c.get('actor'), tenantId, scopeId);
         if (!scope)
             return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
-        const vertical = await verticalForScope(c, scope);
-        return c.json(vertical
-            ? await vertical.readScopeTable(scopeId, input)
-            : await admin.readScopeTable(c.get('actor'), tenantId, scopeId, input));
+        return c.json(await delegatedRead(c, tenantId, scopeId, scope, 'readScopeTable', input, {
+            viaVertical: (v) => v.readScopeTable(scopeId, input),
+            colocated: () => admin.readScopeTable(c.get('actor'), tenantId, scopeId, input),
+        }, (r) => r.rows.length));
     });
     // The SQL console (#219): one read-only statement, POSTed because SQL does not
     // belong in a URL. Same delegation as the table reads; the gate's refusal maps to
@@ -1604,10 +1691,14 @@ export function createControlPlaneApi(options) {
         const scope = await admin.getScopeRecord(c.get('actor'), tenantId, scopeId);
         if (!scope)
             return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
-        const vertical = await verticalForScope(c, scope);
-        return c.json(vertical
-            ? await vertical.queryScope(scopeId, input)
-            : await admin.queryScope(c.get('actor'), tenantId, scopeId, input));
+        return c.json(await delegatedRead(
+        // The SQL is the argument the co-located branch logs, so it is the argument
+        // here — an audit row for the read-only console that did not carry the
+        // statement would answer "someone queried" and nothing a reader needs.
+        c, tenantId, scopeId, scope, 'queryScope', input, {
+            viaVertical: (v) => v.queryScope(scopeId, input),
+            colocated: () => admin.queryScope(c.get('actor'), tenantId, scopeId, input),
+        }, (r) => r.rows.length));
     });
     // The K-35 denial log (#867) — the third of the platform's three logs and the last to
     // get a reader. `/admin-log` holds staff mutations and the K-24 access log staff
@@ -1631,10 +1722,10 @@ export function createControlPlaneApi(options) {
         const scope = await admin.getScopeRecord(c.get('actor'), tenantId, scopeId);
         if (!scope)
             return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
-        const vertical = await verticalForScope(c, scope);
-        return c.json(vertical
-            ? await vertical.listDenials(scopeId, filter)
-            : await admin.listDenials(c.get('actor'), tenantId, scopeId, filter));
+        return c.json(await delegatedRead(c, tenantId, scopeId, scope, 'listDenials', filter, {
+            viaVertical: (v) => v.listDenials(scopeId, filter),
+            colocated: () => admin.listDenials(c.get('actor'), tenantId, scopeId, filter),
+        }, (r) => r.length));
     });
     app.get('/tenants/:tenantId/scopes/:scopeId/denials/summary', async (c) => {
         const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
@@ -1647,10 +1738,10 @@ export function createControlPlaneApi(options) {
         const scope = await admin.getScopeRecord(c.get('actor'), tenantId, scopeId);
         if (!scope)
             return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
-        const vertical = await verticalForScope(c, scope);
-        return c.json(vertical
-            ? await vertical.summarizeDenials(scopeId, filter)
-            : await admin.summarizeDenials(c.get('actor'), tenantId, scopeId, filter));
+        return c.json(await delegatedRead(c, tenantId, scopeId, scope, 'summarizeDenials', filter, {
+            viaVertical: (v) => v.summarizeDenials(scopeId, filter),
+            colocated: () => admin.summarizeDenials(c.get('actor'), tenantId, scopeId, filter),
+        }, (r) => r.buckets.length));
     });
     // The owner seat (#925). Both reads go to the VERTICAL — the seat lives in its identity
     // directory, in its deployment — after the same K-3 cross-check every scope-addressed read
@@ -3707,6 +3798,31 @@ export function createControlPlaneApi(options) {
         });
         return c.json(await options.observability.tenantMetrics(input));
     });
+    // The bucketed twin (#1447): the series a team-level chart plots, one line per app.
+    // Same grain, same forced tenant, same 501 when the reader cannot bucket — an empty
+    // series would render as "quiet". `scopeId` repeats, like `service` on the script-grain
+    // series, so "all my apps" is one read; it is capped because the answer is scopes ×
+    // buckets, and at least one is required because an unnarrowed ask is not on offer.
+    app.get('/observability/tenant-metrics-series', async (c) => {
+        if (!options.observability?.tenantMetricsSeries) {
+            return c.json({ error: 'bucketed tenant-grain observability is not configured on this control plane' }, 501);
+        }
+        const p = c.get('principal');
+        const tenantId = p.kind === 'builder' ? p.tenantId : c.req.query('tenantId');
+        if (!tenantId)
+            throw new ControlPlaneError(400, 'tenantId is required');
+        const scopeIds = (c.req.queries('scopeId') ?? []).filter((s) => s.length > 0);
+        const input = z
+            .object({
+            tenantId: tenantIdSchema,
+            // Narrowing WITHIN the tenant, as on /tenant-metrics: a foreign scope id yields
+            // zero rows rather than somebody else's, so no ownership check is needed here.
+            scopeIds: z.array(z.string().min(1).max(64)).min(1).max(TENANT_SERIES_SCOPE_CAP),
+            hours: z.coerce.number().int().min(1).max(72).default(24),
+        })
+            .parse({ tenantId, scopeIds, hours: c.req.query('hours') });
+        return c.json(await options.observability.tenantMetricsSeries(input));
+    });
     app.get('/observability/tenant-logs', async (c) => {
         if (!options.observability?.tenantLogs) {
             return c.json({ error: 'tenant-grain observability is not configured on this control plane' }, 501);
@@ -3723,7 +3839,35 @@ export function createControlPlaneApi(options) {
             level: z.enum(['log', 'info', 'warn', 'error', 'debug']).optional(),
             search: z.string().min(1).max(200).optional(),
             hours: z.coerce.number().int().min(1).max(72).default(24),
+            // The chart's time cursor (#1447): a window that ENDS in the past, which `hours`
+            // cannot spell — it always ends at now.
+            since: z.string().datetime({ offset: true }).optional(),
+            until: z.string().datetime({ offset: true }).optional(),
             limit: z.coerce.number().int().min(1).max(200).default(100),
+        })
+            .superRefine((v, ctx) => {
+            const now = Date.now();
+            const to = v.until ? Date.parse(v.until) : now;
+            const from = v.since ? Date.parse(v.since) : to - v.hours * 3_600_000;
+            // On the resolved bounds rather than on the pair, so a lone `since` in the future
+            // is refused by the same line: with no `until` it is measured against now, and
+            // without this it would reach the backend as a window that cannot contain
+            // anything and come back as an empty page nobody could explain.
+            if (from >= to) {
+                ctx.addIssue({ code: 'custom', path: ['since'], message: 'since must be before until' });
+            }
+            // The SAME ceiling `hours` carries, applied to the window however it was spelled.
+            // Otherwise the pair is a second door onto a read the first one caps at three
+            // days, and the two spellings together would read past what either allows.
+            if (to - from > 72 * 3_600_000) {
+                ctx.addIssue({ code: 'custom', path: ['since'], message: 'the window may not exceed 72 hours' });
+            }
+            // A window ending in the future returns nothing and says nothing about why, which
+            // a reader takes for "my app was quiet". Five minutes of slack, because the
+            // instant is stamped by a browser's clock rather than by ours.
+            if (to > now + 5 * 60_000) {
+                ctx.addIssue({ code: 'custom', path: ['until'], message: 'until may not be more than 5 minutes in the future' });
+            }
         })
             .parse({
             tenantId,
@@ -3732,6 +3876,8 @@ export function createControlPlaneApi(options) {
             level: c.req.query('level') || undefined,
             search: c.req.query('search') || undefined,
             hours: c.req.query('hours'),
+            since: c.req.query('since') || undefined,
+            until: c.req.query('until') || undefined,
             limit: c.req.query('limit'),
         });
         return c.json(await options.observability.tenantLogs(input));