@friggframework/core 2.0.0--canary.622.eb2c9bd.0 → 2.0.0--canary.622.faffe5f.0

package/application/commands/usage-commands.js

@@ -1,8 +1,8 @@
 /**
  * Usage Commands
  *
- * Application Layer — the read/write surface over the durable usage store
- * (ADR-011 §5). Exposed as `frigg.usage.*` on the unified command object so
+ * Application Layer — the read/write surface over the durable usage store.
+ * Exposed as `frigg.usage.*` on the unified command object so
  * reports and integration code query usage without touching the repository.
  *
  * @example
@@ -33,7 +33,8 @@ function createUsageCommands({ usageRepository, northStar = null } = {}) {
             value = 1,
             at = new Date(),
         }) {
-            for (const window of computeUsageWindows(at)) {
+            const windows = computeUsageWindows(at);
+            for (const window of windows) {
                 await repository.increment({
                     integrationId,
                     integrationType,
@@ -53,7 +54,7 @@ function createUsageCommands({ usageRepository, northStar = null } = {}) {
         },
 
         /**
-         * First-class North Star read (ADR-011 Decision 5). Resolves the
+         * First-class North Star read. Resolves the
          * configured counter for an integration type (byType wins over default),
          * then returns its totals from the durable usage store. Returns `null`
          * when no North Star is configured, so callers can branch without

package/application/index.js

@@ -19,7 +19,7 @@ const { createUsageCommands } = require('./commands/usage-commands');
  * @param {Object} params.integrationClass - Integration class (required)
  * @param {Object} [params.northStar] - Resolved North Star config
  *   (`Definition.telemetry.northStar`) so `frigg.usage.northStar(...)` can read
- *   it (ADR-011 Decision 5). Injected by the caller that owns the app definition
+ *   it. Injected by the caller that owns the app definition
  *   (the handler/report runner) — the application layer never reaches up to load
  *   it. Omitted → usage reads report no North Star.
  * @returns {Object} Unified commands object with all CRUD operations
@@ -57,7 +57,7 @@ function createFriggCommands({ integrationClass, northStar = null }) {
         // Process commands
         ...processCommands,
 
-        // Usage read/write (ADR-011) — nested to match `frigg.usage.*`.
+        // Usage read/write — nested to match `frigg.usage.*`.
         // northStar injected by the caller (composition root), not loaded here.
         usage: createUsageCommands({ northStar }),
     };

package/core/create-handler.js

@@ -153,8 +153,8 @@ const createHandler = (optionByName = {}) => {
                 ? usageRollup
                 : getUsageRollupSubscriber();
 
-        // Wire adopter-declared telemetry subscribers once per cold start
-        // (ADR-011 Decision 6). Memoized in the singleton, so this is a cheap
+        // Wire adopter-declared telemetry subscribers once per cold start.
+        // Memoized in the singleton, so this is a cheap
         // no-op after the first invocation.
         getPluginTelemetrySubscribers();
 

package/handlers/integration-event-dispatcher.js

@@ -25,7 +25,7 @@ class IntegrationEventDispatcher {
     }
 
     /**
-     * Resolve + invoke a handler, auto-instrumented (ADR-011 Decision 2). This
+     * Resolve + invoke a handler, auto-instrumented. This
      * is the seam for queue/webhook/defined-route dispatch; the `this.on` path
      * (user actions, lifecycle) is instrumented in IntegrationBase.send().
      */

package/index.js

@@ -143,7 +143,7 @@ module.exports = {
     createReportingRouter,
     createReportingRepository,
 
-    // telemetry (ADR-011)
+    // telemetry
     createTelemetry,
     getTelemetry,
     createUsageRepository,

package/integrations/integration-base.js

@@ -79,7 +79,7 @@ class IntegrationBase {
         // Tier 3 Integration Extensions — see packages/core/integrations/EXTENSIONS.md
         // Shape: { [bindingName]: { extension, handlers?: { [eventName]: methodName } } }
         extensions: {},
-        // Usage-counter opt-in (ADR-011). Declaring a canonical key opts into the
+        // Usage-counter opt-in. Declaring a canonical key opts into the
         // cross-integration comparison report + durable rollup; custom keys are
         // comparable within this integration type. Shape:
         //   usage: { canonical: ['records.synced', ...], custom: { 'deals.enriched': { unit, label } } }
@@ -108,7 +108,7 @@ class IntegrationBase {
         this.messages = { errors: [], warnings: [] };
         this._isHydrated = false;
 
-        // Telemetry (ADR-011): every instance carries the service so integration
+        // Telemetry: every instance carries the service so integration
         // code can call `this.telemetry.*`. Extracted before the record check so
         // passing only `telemetry` never triggers a hollow hydration. Bound to
         // this instance so emissions auto-carry `integration_type` for the usage
@@ -223,7 +223,7 @@ class IntegrationBase {
 
         this._isHydrated = Boolean(this.id);
 
-        // ADR-011 Decision 2: log the instance-open exactly once per hydrated
+        // Log the instance-open exactly once per hydrated
         // instance, carrying the standard identifier set — so an integration is
         // visible in telemetry even on a path that never dispatches a handler.
         // High-cardinality ids ride the bus context (3rd arg), never metric
@@ -249,7 +249,7 @@ class IntegrationBase {
     }
 
     /**
-     * Standard telemetry identifier set (ADR-011 Decision 3). Assembled from the
+     * Standard telemetry identifier set. Assembled from the
      * hydrated record (integrationId, userId, version), the static Definition
      * (integrationType, version fallback), and the environment (stage, appName).
      * High-cardinality ids (integrationId, userId) ride span baggage only — never
@@ -812,7 +812,7 @@ class IntegrationBase {
                 `Event ${event} is not defined in the Integration event object`
             );
         }
-        // Auto-instrument (ADR-011 Decision 2). This is the seam for user
+        // Auto-instrument. This is the seam for user
         // actions, config-options, and lifecycle events dispatched via `this.on`
         // (the queue/webhook/route paths go through IntegrationEventDispatcher).
         return instrumentHandler(

package/modules/requester/requester.js

@@ -44,7 +44,7 @@ class Requester extends Delegate {
         // Instance methods can use this.fetch without differentiating
         this.fetch = get(params, 'fetch', fetch);
 
-        // Telemetry (ADR-011). Defaults to the process singleton; overridable
+        // Telemetry. Defaults to the process singleton; overridable
         // for tests. Outbound requests are instrumented in `_request`.
         //
         // Attribution boundary: the `frigg.apimodule.requests` OTel metric fires
@@ -103,7 +103,7 @@ class Requester extends Delegate {
     };
 
     /**
-     * Instrumenting entry point (ADR-011 P7). Wraps the whole logical request —
+     * Instrumenting entry point. Wraps the whole logical request —
      * including retry/refresh recursion — in a single span + one
      * `frigg.apimodule.requests` counter, emitted on the `i === 0` boundary so
      * retries are never double-counted. The full URL rides the span only; the

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@friggframework/core",
     "prettier": "@friggframework/prettier-config",
-    "version": "2.0.0--canary.622.eb2c9bd.0",
+    "version": "2.0.0--canary.622.faffe5f.0",
     "dependencies": {
         "@aws-sdk/client-apigatewaymanagementapi": "^3.588.0",
         "@aws-sdk/client-kms": "^3.588.0",
@@ -45,9 +45,9 @@
         }
     },
     "devDependencies": {
-        "@friggframework/eslint-config": "2.0.0--canary.622.eb2c9bd.0",
-        "@friggframework/prettier-config": "2.0.0--canary.622.eb2c9bd.0",
-        "@friggframework/test": "2.0.0--canary.622.eb2c9bd.0",
+        "@friggframework/eslint-config": "2.0.0--canary.622.faffe5f.0",
+        "@friggframework/prettier-config": "2.0.0--canary.622.faffe5f.0",
+        "@friggframework/test": "2.0.0--canary.622.faffe5f.0",
         "@prisma/client": "^6.19.3",
         "@types/lodash": "4.17.15",
         "@typescript-eslint/eslint-plugin": "^8.0.0",
@@ -87,5 +87,5 @@
     "publishConfig": {
         "access": "public"
     },
-    "gitHead": "eb2c9bde95b23f2f854fd5d78b2c5388ac5222d8"
+    "gitHead": "faffe5ff8b3fea6bbb46a52502cbd5b5ecb35559"
 }

package/reporting/reporting-router.js

@@ -40,7 +40,7 @@ function buildTypeLabels() {
 
 function createReportingRouter() {
     const reportingRepository = createReportingRepository();
-    // ADR-011 hand-off: enrich the report with feature-usage columns read from
+    // Enrich the report with feature-usage columns read from
     // the Frigg-owned usage store. Best-effort — a failure to construct it never
     // blocks the structural report.
     let usageRepository = null;

package/reporting/use-cases/list-integrations-report.js

@@ -26,7 +26,7 @@ class ListIntegrationsReport {
             throw new Error('reportingRepository is required');
         }
         this.reportingRepository = reportingRepository;
-        // Optional ADR-011 usage store (the ADR-010 hand-off). When present, the
+        // Optional usage store (the ADR-010 hand-off). When present, the
         // report's byType buckets are enriched with feature-usage columns read
         // ONLY from this store — never an external APM.
         this.usageRepository = usageRepository || null;
@@ -87,7 +87,7 @@ class ListIntegrationsReport {
             bucket.byStatus[statusKey] = (bucket.byStatus[statusKey] ?? 0) + 1;
         }
 
-        // Additive usage columns (ADR-011). Read per-type totals for each
+        // Additive usage columns. Read per-type totals for each
         // canonical counter; a type with no rows reads as 0. Guarded so a usage
         // store failure never breaks the structural report.
         if (this.usageRepository) {

package/telemetry/bind-telemetry-context.js

@@ -1,6 +1,6 @@
 /**
  * Wrap a telemetry service so an integration instance's emissions automatically
- * carry its `integration_type` (ADR-011). This lets developers write
+ * carry its `integration_type`. This lets developers write
  * `this.telemetry.count('records.synced', n, { entity })` with no per-call
  * boilerplate, while the usage rollup still attributes the counter to the right
  * integration type.

package/telemetry/canonical-counters.js

@@ -1,5 +1,5 @@
 /**
- * Canonical usage-counter vocabulary (ADR-011 Usage-Counter Contract §1).
+ * Canonical usage-counter vocabulary.
  *
  * These core-owned, versioned keys are the ONLY metrics guaranteed comparable
  * *across* integration types — they power ADR-010's apples-to-apples comparison

package/telemetry/exporters/exporter-factory.js

@@ -1,6 +1,6 @@
 /**
- * Builds OpenTelemetry span/metric exporters from an app-definition descriptor
- * (ADR-011 Decision 1). All OTel packages are lazy-`require`d here so the no-op
+ * Builds OpenTelemetry span/metric exporters from an app-definition descriptor.
+ * All OTel packages are lazy-`require`d here so the no-op
  * path (which never calls this) loads zero OTel modules.
  *
  * Supported descriptor `type`s:

package/telemetry/instrument-handler.js

@@ -1,6 +1,6 @@
 /**
  * Wraps a single integration handler invocation with a span + the
- * `frigg.handler.invocations` counter (ADR-011 Decision 2). Shared by the two
+ * `frigg.handler.invocations` counter. Shared by the two
  * dispatch seams — `IntegrationBase.send()` and `IntegrationEventDispatcher` —
  * so both paths are instrumented identically.
  *

package/telemetry/no-op-telemetry.js

@@ -8,7 +8,7 @@ const {
  * No-op telemetry implementation.
  *
  * This is the default when no OTel exporter is configured, so telemetry "rides
- * for free" (ADR-011): integration code can call `this.telemetry.*`
+ * for free": integration code can call `this.telemetry.*`
  * unconditionally and it costs nothing on the OTel side. Critically, this module
  * imports **zero** OpenTelemetry packages — the no-op path never loads the OTel
  * SDK (guarded by a require-graph test), protecting Lambda cold-start.

package/telemetry/north-star.js

@@ -1,5 +1,5 @@
 /**
- * Adopter North Star metric (ADR-011 Decision 5). A North Star simply references
+ * Adopter North Star metric. A North Star simply references
  * a usage-counter key (canonical or custom); its value is then read like any
  * other counter via `frigg.usage.totals({ metric: northStarKey })`. It is
  * populated either by (a) direct emission of that counter, or (b) derived from a

package/telemetry/otel-telemetry.js

@@ -47,7 +47,7 @@ function ensureContextManager() {
 }
 
 /**
- * The OpenTelemetry-backed telemetry service (ADR-011 Decision 1). Reached only
+ * The OpenTelemetry-backed telemetry service. Reached only
  * when a real exporter is configured; `createTelemetry` returns the no-op
  * otherwise. `BatchSpanProcessor` is used uniformly — spans are delivered by the
  * bounded `forceFlush()` the Lambda handler awaits before the container freezes

package/telemetry/plugin-subscribers-singleton.js

@@ -1,8 +1,8 @@
 const { wireTelemetrySubscribers } = require('./plugin-subscribers');
 
 /**
- * Process-wide wiring of adopter-declared telemetry subscribers (ADR-011
- * Decision 6). Built once per cold start and reused for the life of the Lambda
+ * Process-wide wiring of adopter-declared telemetry subscribers. Built once per
+ * cold start and reused for the life of the Lambda
  * container, mirroring the usage-rollup singleton. Independent of the usage
  * rollup: adopter taps wire even when no integration declares `Definition.usage`.
  * Never throws — a bad/absent app definition just means no adopter taps.

package/telemetry/plugin-subscribers.js

@@ -1,5 +1,5 @@
 /**
- * Declarative plugin/extension telemetry taps (ADR-011 Decision 6).
+ * Declarative plugin/extension telemetry taps.
  *
  * The built-in usage rollup and North Star derivation subscribe to the telemetry
  * bus in framework code; this lets an ADOPTER subscribe declaratively from the

package/telemetry/telemetry-config.js

@@ -1,6 +1,6 @@
 /**
  * Resolves and validates the telemetry section of an app definition
- * (ADR-011 Decisions 1 & 5) into a normalized config the TelemetryService and
+ * into a normalized config the TelemetryService and
  * usage rollup consume: `{ exporter, northStar, sampleRatio }`.
  *
  * Exporter default is keyed off STAGE: only a genuinely LOCAL run (STAGE=local)

package/telemetry/telemetry-context.js

@@ -1,7 +1,7 @@
 const { AsyncLocalStorage } = require('node:async_hooks');
 
 /**
- * Ambient telemetry context (ADR-011). A single process-wide AsyncLocalStorage
+ * Ambient telemetry context. A single process-wide AsyncLocalStorage
  * holds the standard identifiers ({integrationId, integrationType, userId,
  * version, ...}) for the duration of a handler, set once at the handler seam via
  * `telemetry.withContext(...)`. Any emission during that async scope — including

package/telemetry/telemetry-event-bus.js

@@ -1,6 +1,6 @@
 /**
- * TelemetryEventBus — the internal event stream telemetry flows onto
- * (ADR-011 Decision 6). Plugins/extensions and the built-in usage rollup
+ * TelemetryEventBus — the internal event stream telemetry flows onto.
+ * Plugins/extensions and the built-in usage rollup
  * subscribe here; it is deliberately independent of OTel export (Decision 7),
  * so usage counters persist even when the OTel exporter is a no-op.
  *

package/telemetry/telemetry-service.js

@@ -12,7 +12,7 @@ function isNoOpExporter(exporter) {
 }
 
 /**
- * Create the vendor-neutral telemetry service (ADR-011 Decision 1).
+ * Create the vendor-neutral telemetry service.
  *
  * Integration code uses the returned object (`this.telemetry`) and never imports
  * a backend SDK. When no exporter is configured the service is a pure no-op that
@@ -26,8 +26,8 @@ function isNoOpExporter(exporter) {
  * @param {object} [options.bus] Event bus to reuse (defaults to a fresh one).
  */
 function createTelemetry(options = {}) {
-    // The internal event stream is always on and independent of OTel export
-    // (ADR-011 Decision 7): the usage rollup + plugin taps must work even when
+    // The internal event stream is always on and independent of OTel export:
+    // the usage rollup + plugin taps must work even when
     // the OTel exporter is a no-op. The bus is pure JS, so this does not load
     // any OTel module on the no-op path.
     const bus = options.bus || createTelemetryEventBus();

package/telemetry/telemetry-singleton.js

@@ -2,7 +2,7 @@ const { createTelemetry } = require('./telemetry-service');
 const { createNoOpTelemetry } = require('./no-op-telemetry');
 
 /**
- * Process-wide telemetry singleton (ADR-011 P4). Created lazily on first use and
+ * Process-wide telemetry singleton. Created lazily on first use and
  * reused for the life of the Lambda container, so the OTel SDK initialises at
  * most once per cold start. Building it never throws — any failure (e.g. no app
  * definition on disk in a unit test) falls back to the no-op so a handler is

package/telemetry/usage-rollup-singleton.js

@@ -1,7 +1,7 @@
 const { createUsageRollupSubscriber } = require('./usage-rollup-subscriber');
 
 /**
- * Process-wide usage-rollup subscriber (ADR-011 P9). Built once per cold start,
+ * Process-wide usage-rollup subscriber. Built once per cold start,
  * subscribed to the telemetry singleton's bus, and reused across invocations.
  * Returns null when usage is disabled (no integration declares Definition.usage)
  * or when the app definition can't be loaded — the handler then skips the flush.

package/telemetry/usage-rollup-subscriber.js

@@ -3,8 +3,8 @@ const { computeUsageWindows } = require('./usage-windows');
 const WEBHOOK_EVENT_NAMES = new Set(['ON_WEBHOOK']);
 
 /**
- * Framework auto-signal metric names → the canonical usage key they feed
- * (ADR-011 §3). Resolvers receive (attributes, context) and may return null to
+ * Framework auto-signal metric names → the canonical usage key they feed.
+ * Resolvers receive (attributes, context) and may return null to
  * decline. Handler invocations map by event: USER_ACTION → user_actions; the
  * DB-connected `ON_WEBHOOK` queue dispatch → webhooks.received (per-integration,
  * and where a durable write is actually possible — the HTTP receipt handler is
@@ -22,7 +22,7 @@ const METRIC_TO_CANONICAL = {
 };
 
 /**
- * The built-in usage-rollup subscriber (ADR-011 Decision 7). Subscribes to the
+ * The built-in usage-rollup subscriber. Subscribes to the
  * telemetry event bus and folds *declared* counters (canonical or custom) into
  * the durable usage store. It buffers within an invocation and writes on
  * `flush()` (no timers — Lambda-safe), or drops the buffer on `discard()` for an

package/telemetry/usage-windows.js

@@ -1,5 +1,5 @@
 /**
- * Compute the rollup window keys a usage event falls into (ADR-011 §4).
+ * Compute the rollup window keys a usage event falls into.
  * Windows are UTC and prefixed by their granularity so the store can filter a
  * series by bucket (`window startsWith 'day:'`).
  *

package/usage/repositories/usage-repository-interface.js

@@ -1,5 +1,5 @@
 /**
- * Port for the durable usage-counter store (ADR-011 Usage-Counter Contract §4).
+ * Port for the durable usage-counter store.
  *
  * The store is deliberately isolated (ADR-010 Decision 3): its fact rows carry
  * NO userId and NO foreign key to Integration, so a user-scoped query can never

package/usage/repositories/usage-repository-postgres.js

@@ -2,7 +2,7 @@ const { prisma } = require('../../database/prisma');
 const { UsageRepositoryInterface } = require('./usage-repository-interface');
 
 /**
- * Prisma-backed usage store (ADR-011 §4). This is the canonical implementation;
+ * Prisma-backed usage store. This is the canonical implementation;
  * because Prisma abstracts the underlying database, the Mongo and DocumentDB
  * adapters extend this class unchanged (see their files). All queries touch only
  * the isolated `UsageCounter` model — never user/integration-scoped tables.

package/usage/tracked-metrics.js

@@ -2,7 +2,7 @@ const { isCanonicalCounter } = require('../telemetry/canonical-counters');
 
 /**
  * Compute the set of usage-counter keys the rollup should persist, from each
- * integration's `Definition.usage` opt-in (ADR-011 Usage-Counter Contract §2).
+ * integration's `Definition.usage` opt-in.
  * Declaring a canonical key opts into cross-type comparison + the rollup; custom
  * keys are tracked per integration type. Unknown canonical keys are dropped with
  * a warning (lazy validation, matching how Definition is treated elsewhere).