@pikku/core 0.12.106 → 0.12.111

package/CHANGELOG.md

@@ -1,3 +1,361 @@
+## 0.12.111
+
+### Patch Changes
+
+- 78237ac: The console shows feature flags as a launch board, and analytics events as a
+  declared catalog.
+
+  A flag's state is four fields — `enabled`, `rolloutPercent`, `declared`,
+  `backed` — and none of them is the question an operator actually asks, which is
+  how far this has got. The board answers that directly: every declared flag sits
+  in the lane its rollout has reached, `dark` → `rolling` → `live`, with
+  `attention` for the flags that are not resolving in a way anybody chose.
+
+  Attention is evaluated before every other reading, and that ordering is the
+  whole point rather than an implementation detail. A flag declared in code with
+  no row in the store fails open, and it reports `enabled: true` with no rollout
+  limit — byte-identical to a deliberate full launch. Read the fields in the
+  obvious order and the one production-severity state on the board renders as the
+  healthiest one. `groupFlagsByLane` also returns all four lanes whether or not
+  they hold anything, because a board read by shape must not rearrange itself the
+  moment a lane empties.
+
+  Selecting a flag opens its controls beside the board rather than over it: the
+  switch, the rollout bucket, and the subjects pinned on or off past that bucket.
+  They share one surface because they are read together — "off for everyone except
+  these three" is a switch and an override row, and an operator who has to leave
+  one screen to see the other is the operator who turns a flag on for everybody by
+  mistake. The panel tracks the open flag by name and re-reads it from the list, so
+  committing a rollout moves the card and the panel together instead of leaving the
+  panel describing the flag as it was before the operator changed it.
+
+  A board whose flags come from a `FeatureFlagSource` — a provider Pikku reads but
+  does not own — says so and offers no controls, rather than offering controls that
+  would fail.
+
+  The analytics screen is a catalog of what the code declares, read from build-time
+  meta: the events a client may emit and the props each carries, with every prop
+  rendered as the schema source text the declaration wrote. It is deliberately not
+  a volume report — nothing here counts what was emitted — and saying which of the
+  two it is turned out to be the only design question the screen had.
+
+  Turning a flag on while it carries no rollout limit now asks first. That press
+  is the one irreversible thing the board can do — with no bucket left to hold
+  anybody back it admits everyone the flag's capabilities allow — and it used to
+  be a single click on a switch. The panel also reports what a mutation is doing
+  and what it refused to do: the controls it is waiting on go into a pending
+  state, and a failed write raises an inline `<Alert>` rather than reverting in
+  silence. The console mounts no notification provider, so the feedback is inline
+  where the action is, which is the idiom the rest of the console already uses.
+
+  `@pikku/mantine`'s theme gains four aliases, and they close a contrast defect
+  that predates this board:
+
+  ```ts
+  '--mantine-color-orange-light': 'var(--app-surface-warning)',
+  '--mantine-color-orange-light-color': 'var(--app-amber)',
+  '--mantine-color-teal-light': 'var(--app-surface-success)',
+  '--mantine-color-teal-light-color': 'var(--app-green)',
+  ```
+
+  The theme already documents two colour tiers — TEXT must clear AA, GRAPHIC only
+  3:1 — and already pulls Mantine's own variables into that contract rather than
+  linting call sites. What it had not covered was Mantine's _light variants_:
+  `<Alert color="orange">` renders #d9480f on #ffe8cc at 3.62:1, and
+  `<Badge variant="light" color="teal">` at 4.33:1, neither reachable from an
+  `--app-*` token because the component never asks for one. The ramp itself is
+  deliberately untouched: Mantine conflates `--mantine-color-orange-filled`
+  between `c="orange"` text and a `variant="filled"` background, so darkening it
+  for light-mode text would make an existing filled badge unreadable in dark mode.
+  Eight pre-existing `c="orange"` call sites moved onto the amber TEXT tier in the
+  same pass.
+
+  The analytics catalog is grouped by the file that declares each event, and its
+  rows are real buttons rather than table cells carrying a tabindex.
+
+  `ShellHeaderAction` gains `loading` and `testId`, and `ActionCluster` gains a
+  `measurement` flag. `ShellHeader` sizes its actions by rendering them a second
+  time off-screen, and that measuring copy was carrying the same `data-testid` and
+  `data-help` as the real one — so every action on a page with a collapsing header
+  resolved to two elements. The flags board also moved its two header actions from
+  `actionsNode` (documented as the non-collapsing escape hatch) onto the structured
+  `actions` array, which is what stopped them clipping off the right edge at 400px.
+
+- add56d2: Reading webhook deliveries no longer throws when nothing persists them.
+
+  `WebhookService.listDeliveries` and `getDelivery` return `[]`/`null` instead of `NotImplementedError`, so the console's webhooks page shows an empty list on an app whose service only delivers. `recordAttempt` still throws — a write that goes nowhere loses the caller's data.
+
+## 0.12.110
+
+### Patch Changes
+
+- 1c9a55a: Analytics can fan out to several destinations, and carry the identity an ad
+  platform needs.
+
+  `fanOutAnalytics` composes any number of destinations into one
+  `AnalyticsService`, so a single-destination app never meets it and a sink is the
+  same class whether it runs alone or beside three others. Destinations are
+  settled rather than awaited in sequence: `flush()` runs inside the invocation,
+  so a slow vendor must not add its latency to the request and a vendor that is
+  down must not cost the others their events.
+
+  Each destination takes an optional `accepts` predicate. Which events a
+  destination receives is the app's policy — a product-analytics tool wants
+  everything, an ad platform wants three conversions — while what an event should
+  look like once it arrives is the sink's, and belongs in its mapper rather than
+  in a central mapping table that would push vendor trivia into every app.
+
+  `AnalyticsIdentity` gains `vendorIds` and `consent`. GA4 keys on a `client_id`
+  from the `_ga` cookie and Meta on `fbp`/`fbc`; neither is derivable from a user
+  id, so a server-side sink without them does not degrade, it sends nothing
+  usable. Both are resolved server-side through an `analyticsIdentity` resolver on
+  singleton services, never read from the event body — the same rule the rest of
+  the identity already follows, so a crafted client call cannot attribute an event
+  to someone else. `cookieAnalyticsIdentity` covers the common first-party-cookie
+  case; a consent tool that packs every purpose into one encoded blob writes its
+  own resolver, which is why the resolver is a function.
+
+  A resolver returns nothing off a wire with no browser behind it, so a cron task
+  and a queue worker never invent a vendor id.
+
+  The analytics leaf re-exports the runtime, so an app reaches the whole surface
+  through `#pikku/analytics` — wiring where events go sits next to declaring them,
+  and splitting that across two specifiers splits one concern across two names.
+
+  Identity the browser owns is resolved server-side, and can now be created there
+  too. `cookieAnalyticsIdentity` reads GA4's `client_id` and Meta's `fbp`/`fbc`
+  off first-party cookies; `mintCookie` writes one that is not there yet, which is
+  what lets an app collect nothing on the page at all. Both formats are public and
+  server-side minting is documented by the vendors — it is the mechanism behind
+  server-side tagging, offered here as a wired resolver rather than a second
+  container to operate.
+
+  Minting is gated on consent, because writing the cookie is itself the act
+  consent governs — a minter that runs before the banner is answered has already
+  done the thing the send gate was meant to prevent. `composeAnalyticsIdentity`
+  exists to make that expressible: resolvers run in order and each sees what the
+  ones before it produced, so the reader that finds consent necessarily precedes
+  the minter that needs it. Every required purpose must be granted, not any.
+
+  `anonymousAnalyticsIdentity` fills the gap that made anonymous product analytics
+  dishonest. `pikkuUserId` is derived from a session and so is absent for exactly
+  the visitor it would need to identify, which left a sink choosing between
+  collapsing every anonymous visitor into one shared literal and dropping the
+  pre-signup funnel entirely. The id is `httpOnly` by default: no browser script
+  needs it, and a cookie scripts cannot touch is not subject to the seven-day cap
+  browsers place on script-set ones.
+
+  On the client, `createAnalytics` takes an `enabled` predicate checked at each
+  flush. A boolean would be captured before anyone had answered the banner, so
+  accepting mid-session would never start and withdrawing would never stop.
+  Refused events are discarded rather than held, so changing your mind does not
+  release a backlog.
+
+- 1c9a55a: Review fixes across the feature-flag and analytics primitives:
+
+  - An addon function's `featureFlag:` gate now reads the consuming application's
+    flag source rather than the package's own services, which never carry one.
+  - A flag named `__proto__`, `constructor` or `prototype` is rejected instead of
+    being silently dropped from the generated metadata.
+  - Two declarations of one flag with different descriptions are a hard error,
+    rather than the inspector's traversal order deciding what operators read.
+  - `subjectIdOf` falls through an empty organization id to the user, instead of
+    resolving to no subject and skipping every override and rollout bucket.
+  - `CachedFlagSource.invalidate()` retires the in-flight read, so a webhook that
+    lands mid-fetch is not answered by the pre-webhook snapshot for another TTL.
+  - The generated `/feature-flags` wire resolves against the compiled fallback
+    when no source is wired, so a scope-gated flag is not reported to a caller
+    who cannot hold it.
+  - `pruneFlags()` rechecks `declared = false` in the delete and reports only
+    what it removed, so a redeclaration between the two keeps its overrides.
+  - A destination's `accepts` throwing no longer costs every later sink its batch.
+  - The React analytics client drops events at collection time when analytics is
+    disabled, so a later consent grant cannot send what was gathered before it.
+  - The React flag client keeps its map when the wire answers a non-object.
+  - `KyselyAnalyticsService` mints event ids from `crypto` rather than a
+    timestamp with a short random tail.
+
+- 1c9a55a: Feature flags, declared in source and resolved from two independent booleans.
+
+  `defineFeatureFlags` declares a flag the way `defineScopes` declares a scope —
+  the inspector collects it, the CLI emits a `FeatureFlagName` union, and a
+  misspelled `featureFlag:` is a type error rather than a gate that silently fails
+  open.
+
+  A flag answers two questions that are not the same question. `capable` comes
+  from the session's scopes and is per-user, advisory, and protects nothing — it
+  hides UI. `available` comes from one global config snapshot, is caller-blind,
+  and is the only half the runner enforces: `override(subject) ?? (enabled AND
+bucket)`, so "off for everyone except these three organizations" is one row, and
+  a kill is one write rather than a fan-out. Authorization stays where it was, in
+  the function's own `scopes:` — enforcing capability would make a flag a second
+  authorization path OR-ing against them. An unavailable feature throws 503, not
+  403, because the caller was allowed; the feature was not on.
+
+  `featureFlag:` is deliberately available on sessionless functions too. It reads
+  the config, not the session, so the kill switch reaches a cron task, a queue
+  worker and a webhook — which is where it matters most, since nobody is watching
+  a UI to notice the feature is off.
+
+  Refresh is pull-on-demand, so the TTL is the kill-switch latency. Where that is
+  too long, `invalidate()` is public: a provider's change webhook lands on an HTTP
+  wiring, drops the cache, and the next request does the read. It deliberately
+  does not fetch — a burst of webhooks would be N round trips, and on a serverless
+  runtime the isolate that took the signal may be gone before anything reads the
+  result.
+
+  Availability fails open through three layers: a fresh read, then the last good
+  cached read, then the compiled declaration. The middle layer is load-bearing —
+  dropping straight to the compiled fallback on a blip would switch on every flag
+  that was deliberately dark.
+
+  Backing stores split along what they can honestly do. `FeatureFlagSource` is
+  read-only (`snapshot()`) and is what a third-party provider implements;
+  `FeatureFlagStore` adds the write half and is for stores Pikku owns.
+  `@pikku/kysely` ships the store, with declarations synced additively — a removed
+  declaration is marked undeclared, never revoked, and a sync never re-enables a
+  killed flag. Third-party providers implement the read-only half in the addons
+  repository, over plain `fetch` rather than a vendor SDK — those poll on a timer
+  belonging to a long-lived process, which a serverless isolate cannot hold
+  between requests.
+
+  A client asks for its flags once per session rather than per flag:
+  `scaffold.featureFlags` generates a `GET /feature-flags` returning every
+  declared flag resolved for the caller, keyed by this app's `FeatureFlagName`.
+  Generated into the app rather than shipped in an addon precisely for that union
+  — an addon never sees the host's, and could only answer
+  `Record<string, boolean>`. It returns `show` alone: sending `available` apart
+  from `capable` would tell every visitor which features exist but are dark.
+
+  The write half is the operator's, and lives in `@pikku/addon-admin` beside the
+  scope RPCs, under a new `admin:flags` scope. `flagList` reports `writable:
+false` rather than failing when flags come from a provider, because a provider's
+  own UI is its operator surface and a console full of buttons that 500 is worse
+  than a read-only tab. It still lists the flags: a source may report its declared
+  set through `declaredFlags()`, and each row carries `backed`, false where the
+  provider has never heard of a declared flag. That row is the one worth seeing —
+  an absent row fails open, so a dark launch nobody created in PostHog is already
+  live for everyone, and a store pikku owns can reconcile that on deploy where a
+  provider cannot.
+
+  On the client, `createFeatureFlags` fetches that map once and `useFeatureFlag`
+  reads it synchronously after, through the same provider the analytics client
+  hangs off. It takes a `bootstrap` map so a server-rendered page hydrates onto
+  the answer it already computed: without one there is a gap in which neither
+  default is right, since false hides a feature the user has and true flashes one
+  they do not. A failed refresh keeps the map already on screen rather than
+  relabelling every flag on a blip.
+
+## 0.12.109
+
+### Patch Changes
+
+- 54138b1: Product analytics moves into core behind a `scaffold.analytics` generator.
+
+  An app declares what it measures, and nothing else:
+
+  ```ts
+  import { defineAnalyticsEvents } from '#pikku/analytics'
+
+  export const analyticsEvents = defineAnalyticsEvents({
+    page_viewed: z.object({ path: z.string() }),
+    todo_created: z.object({ priority: z.enum(['low', 'medium', 'high']) }),
+  })
+  ```
+
+  The definer reaches an app through the generated `#pikku/analytics` leaf, the
+  way `defineFeatureFlags` reaches it through `#pikku/scopes` — an app declares
+  what it measures without importing out of core. The leaf is written on every
+  run, whatever `scaffold.analytics` says: the declaration is how a project names
+  what it measures, and the scaffold only decides whether an ingest wire is
+  generated for it. Its path is `analyticsTypesFile`, defaulting to
+  `<outDir>/analytics/pikku-analytics-types.gen.ts`. It carries the sink surface
+  as well as the definer — `AnalyticsService`, `AnalyticsRecord`,
+  `AnalyticsIdentity`, `AnalyticsClientContext`, `AnalyticsLog`,
+  `LoggerAnalyticsService` — because writing the destination events go to is the
+  other half of the same job, and both halves should come through one door.
+
+  The name is the key, so it is never repeated as a `z.literal` inside the
+  schema. Declare in as many modules as suits the project — a feature declares
+  its events beside its functions — and the CLI unions them into the generated
+  `/analytics` ingest and its schemas. The inspector finds the declarations the
+  way it finds every other wiring, so there is no path to configure.
+
+  Where events go is not part of the declaration. `services.analytics` is the
+  request-scoped buffer a function records into, typed against the declared
+  names:
+
+  ```ts
+  await analytics.record({ name: 'todo_created', priority: 'high' })
+  ```
+
+  It stamps identity, trace and wire fields from the invocation, buffers for the
+  length of the call and flushes once when it ends. Identity is always
+  server-side and never read from a request body, which is what makes the
+  unauthenticated ingest safe to expose.
+
+  The transport behind it is an `AnalyticsService` on singleton services — the
+  one swappable slot. With none wired the runner installs
+  `LoggerAnalyticsService`, so an app that turns the scaffold on can watch events
+  arrive without first choosing a store; a platform injects its own through
+  singleton services, and an app that wants neither sets `analyticsService` in
+  its own `services.ts`, which runs last and wins. There is no process-global
+  sink registry and no noop: events are never silently dropped.
+
+  The generated wire is added to the set of scaffolds the inspector reads.
+  Nothing imports it — it is a wiring, not a module anyone calls — so without
+  that the route was written and never registered: no HTTP wiring, no entry in
+  the fetch client, an endpoint that 404s.
+
+  No middleware is emitted with the wire: an origin lock rejects every native
+  client and is forgeable anyway, so guarding the route is the project's call.
+
+  `name` belongs to the event, not to its props. The generated union rebuilds
+  each member from the declared schema's shape and attaches the literal name
+  last, so a declaration that happens to carry a `name` prop of its own cannot
+  displace the discriminator the union is built on. Props schemas are typed to
+  require that shape, so a schema that has none — a union, a primitive — is
+  refused at the declaration rather than in generated code.
+
+## 0.12.108
+
+### Patch Changes
+
+- 4c7a1b5: Run the monorepo's own scripts through bun instead of yarn. What moves is the
+  package manager each package's `prepublishOnly` and build scripts invoke, plus
+  the two manifest fixes bun needs to resolve the tree: `uWebSockets.js` is
+  declared with an explicit `github:` specifier, and `@pikku/uws-handler` marks
+  its `uWebSockets.js` peer optional so a bun install of a consumer that brings
+  its own uWS app does not try to fetch it from the registry.
+
+  Three published behaviours change, all of them cases where an isolated
+  `node_modules` or bun as the runtime had been papered over by yarn's hoisting:
+
+  - `@pikku/migrator-sql` turns foreign keys on when it opens a sqlite database
+    through bun. `node:sqlite` enforces them by default and `bun:sqlite` does not,
+    which silently turned every `ON DELETE CASCADE` into a no-op under
+    `bunx --bun pikku`.
+  - `@pikku/cli` resolves a deploy provider against the project being deployed
+    rather than against wherever the CLI itself is installed, which is what its
+    own "is not installed" error asks the user to arrange.
+  - `@pikku/cli` treats a specifier a runtime hands straight back — bun does this
+    for the modules it implements itself — as not resolved from the project, so
+    it falls back rather than loading the runtime's own copy.
+
+## 0.12.107
+
+### Patch Changes
+
+- b28a8c0: An addon's exposed functions get their own deployment unit
+
+  `collectFilterNames` adds the `/rpc/:rpcName` scaffold name to every unit holding an exposed function, so that unit can serve its own `/rpc/<funcName>`. `filterInspectorState` read that same string back as "this unit is the generic dispatcher" and kept every wired addon's declaration for it, so almost every function unit imported each addon's whole package bootstrap — and the node-only modules it reaches.
+
+  No unit retains a wired addon on the strength of a catch-all route any more. Instead the analyzer emits a unit per addon carrying that addon's exposed functions, and the unit serving `/rpc/:rpcName` dispatches to it over a service binding rather than bundling it. Granularity is per addon rather than per function because an addon publishes a single prebuilt bootstrap that registers all of its functions at once.
+
+  `node:child_process` joins `node:fs` as a stubbed builtin: Workers have no implementation of it under any compatibility flag, and it is reached from the console addon's audit tooling.
+
+  `DeploymentUnit` gains `dispatch`, an RPC-name → unit-name map for calls whose target unit isn't the kebab-cased RPC name. `rpc.exposed(name)` falls through to the deployment service for a namespaced name with no local metadata, and Cloudflare function units with a `dependsOn` now get a `deploymentService`, which previously only gateway units had.
+
 ## 0.12.106
 
 ### Patch Changes

package/dist/analytics/analytics.d.ts

@@ -0,0 +1,6 @@
+import type { CoreUserSession, PikkuWire } from '../types/core.types.js';
+import type { Logger } from '../services/logger.js';
+import type { AnalyticsEventBase, AnalyticsEventInput, AnalyticsIdentityResolver, AnalyticsLog, AnalyticsService } from './analytics.types.js';
+/** Removes the discriminator, so `props` is free of the series key. */
+export declare const flattenAnalyticsEvent: (event: AnalyticsEventBase, at?: number) => AnalyticsEventInput;
+export declare const createInvocationAnalytics: (service: AnalyticsService, wire: PikkuWire<any, any, any, CoreUserSession>, logger?: Logger, resolveIdentity?: AnalyticsIdentityResolver) => AnalyticsLog;

package/dist/analytics/analytics.js

@@ -0,0 +1,58 @@
+/** Removes the discriminator, so `props` is free of the series key. */
+export const flattenAnalyticsEvent = (event, at) => {
+    const { name, ...props } = event;
+    return { name, props, ...(at === undefined ? {} : { at }) };
+};
+class InvocationAnalyticsLog {
+    service;
+    wire;
+    logger;
+    resolveIdentity;
+    buffer = [];
+    constructor(service, wire, logger, resolveIdentity) {
+        this.service = service;
+        this.wire = wire;
+        this.logger = logger;
+        this.resolveIdentity = resolveIdentity;
+    }
+    async record(event, client) {
+        this.buffer.push(this.resolveEvent(event, client));
+    }
+    async flush() {
+        if (this.buffer.length === 0)
+            return;
+        const batch = this.buffer.splice(0, this.buffer.length);
+        try {
+            await this.service.write(batch);
+        }
+        catch (error) {
+            const logger = this.wire.logger ?? this.logger;
+            logger?.warn?.('analytics flush failed', error);
+        }
+    }
+    async close() {
+        await this.flush();
+    }
+    resolveEvent(event, client) {
+        const session = this.wire.session;
+        const { name, props } = flattenAnalyticsEvent(event);
+        const resolved = this.resolveIdentity?.(this.wire);
+        return {
+            name,
+            props,
+            occurredAt: new Date().toISOString(),
+            ...(client?.at === undefined ? {} : { at: client.at }),
+            userIdentity: {
+                userId: session?.userId ?? null,
+                orgId: session?.orgId,
+                pikkuUserId: this.wire.pikkuUserId,
+                ...resolved,
+            },
+            traceId: this.wire.traceId,
+            functionId: this.wire.functionId,
+            wireType: this.wire.wireType,
+            source: client === undefined ? 'server' : 'client',
+        };
+    }
+}
+export const createInvocationAnalytics = (service, wire, logger, resolveIdentity) => new InvocationAnalyticsLog(service, wire, logger, resolveIdentity);

package/dist/analytics/analytics.types.d.ts

@@ -0,0 +1,156 @@
+import type { CoreUserSession, PikkuWire, PikkuWiringTypes } from '../types/core.types.js';
+/**
+ * The constraint a project's declared event union is checked against.
+ *
+ * Only `name` is fixed, because the name is the whole of what pikku itself
+ * reads — everything else on an event belongs to the app and to the sinks it
+ * wires, and narrowing it here would make the generic useless for anyone whose
+ * events carry more than a fixed set of props.
+ */
+export type AnalyticsEventBase = {
+    name: string;
+} & Record<string, unknown>;
+export interface AnalyticsEventInput {
+    name: string;
+    props?: Record<string, unknown>;
+    at?: number;
+}
+/**
+ * Stamped server-side from the session and never read from the request body,
+ * which is what makes an unauthenticated ingest safe to expose.
+ */
+export interface AnalyticsIdentity {
+    userId: string | null;
+    orgId?: string;
+    pikkuUserId?: string;
+    /**
+     * Identifiers a destination keys on that pikku does not mint — GA4's
+     * `client_id`, Meta's `fbp` and `fbc`, a vendor's own device id. All of them
+     * originate in the browser, and a sink that cannot produce one does not
+     * degrade, it sends nothing usable.
+     *
+     * Resolved server-side from first-party cookies on the request, never read
+     * from the event body, on the same reasoning as the rest of this object: a
+     * crafted client call must not be able to attribute an event to someone else.
+     */
+    vendorIds?: Record<string, string>;
+    /**
+     * A device-scoped id for a visitor with no session, minted by pikku rather
+     * than by a vendor.
+     *
+     * Distinct from `pikkuUserId`, which is derived from a session and is
+     * therefore absent for exactly the visitor this identifies. Without it a
+     * product-analytics sink has no honest option for anonymous traffic: keying
+     * on a shared literal collapses every visitor into one person, and dropping
+     * the event loses the whole pre-signup funnel.
+     */
+    anonymousId?: string;
+    /**
+     * What the visitor agreed to, keyed by purpose. A sink gated on a purpose
+     * absent here does not send.
+     *
+     * Open-ended rather than a fixed pair, because the purposes are the consent
+     * tool's vocabulary and jurisdictions do not agree on them. Undefined means
+     * the app wired no consent resolver, not that consent was refused — the gate
+     * belongs to the sink, which is where the app decides what absence means.
+     */
+    consent?: Record<string, boolean>;
+}
+/**
+ * Resolves the half of the identity pikku cannot know, from the wire.
+ *
+ * A function rather than a cookie-name map because consent tools do not store
+ * one boolean per cookie — a single encoded blob is more common — and a map
+ * could only express the easy case. {@link cookieAnalyticsIdentity} covers that
+ * easy case.
+ */
+export type AnalyticsIdentityResolver = (wire: PikkuWire<any, any, any, CoreUserSession>, 
+/**
+ * What the resolvers before this one produced, when composed. A minter needs
+ * it: whether it may write a cookie at all depends on consent another
+ * resolver read, and ordering is the only thing that can express that.
+ */
+resolved?: Pick<AnalyticsIdentity, 'vendorIds' | 'consent' | 'anonymousId'>) => Pick<AnalyticsIdentity, 'vendorIds' | 'consent' | 'anonymousId'> | undefined;
+/**
+ * What an event becomes once pikku has accepted it, and the only shape an
+ * {@link AnalyticsService} is ever handed.
+ *
+ * Distinct from {@link AnalyticsEventInput}, which is what a caller submits:
+ * the identity, the trace and the origin are stamped server-side on the way
+ * through, so a sink never has to trust — or re-derive — any of them.
+ */
+export interface AnalyticsRecord {
+    name: string;
+    props?: Record<string, unknown>;
+    occurredAt: string;
+    at?: number;
+    userIdentity: AnalyticsIdentity;
+    traceId?: string;
+    functionId?: string;
+    wireType?: PikkuWiringTypes;
+    source: 'server' | 'client';
+}
+/**
+ * Where accepted events go. Pikku validates, identifies and batches them; it
+ * does not store them.
+ *
+ * One method, taking a batch, because a batch is what a destination is always
+ * handed: the invocation buffers and flushes once, and a lone event is a batch
+ * of one. A single-event method beside it would be a second path every sink had
+ * to implement and every caller had to choose between.
+ */
+export interface AnalyticsService {
+    write(batch: AnalyticsRecord[]): Promise<void>;
+}
+/**
+ * One destination in a fan-out, with the events it is allowed to receive.
+ *
+ * `accepts` is the app's, not the sink's: which events a destination should get
+ * is policy — a product-analytics tool wants everything, an ad platform wants
+ * three conversions, and a consent gate reads the same way. What each event
+ * should look like once it gets there is the sink's, and lives in its mapper.
+ */
+export interface AnalyticsSink {
+    service: AnalyticsService;
+    accepts?: (record: AnalyticsRecord) => boolean;
+}
+/**
+ * Its presence, not `at`, is what marks a record as relayed from a browser — a
+ * beacon is free to omit `at`.
+ */
+export interface AnalyticsClientContext {
+    at?: number;
+}
+/**
+ * `services.analytics`: buffered for the invocation, flushed when it ends,
+ * always best-effort. `record` is a method rather than a property so an app can
+ * narrow `Events` in its own `SingletonServices`.
+ */
+export interface AnalyticsLog<Events extends AnalyticsEventBase = AnalyticsEventBase> {
+    record(event: Events, client?: AnalyticsClientContext): Promise<void>;
+    flush(): Promise<void>;
+    close(): Promise<void>;
+}
+/**
+ * One declared event, as an administration surface sees it.
+ *
+ * Read off the declaration at build time rather than from a record: the catalog
+ * has to list an event nobody has fired yet, which is exactly the event someone
+ * is looking for when they open it.
+ */
+export interface AnalyticsEventMeta {
+    /** The event name a client emits, exactly as the declaration spells it. */
+    name: string;
+    /** The module holding the `defineAnalyticsEvents` call that declares it. */
+    file: string;
+    /** The name that module exports the declaration under. */
+    variable: string;
+    /**
+     * The event's props, keyed by name, valued with the schema's own source text
+     * (`z.string()`). Absent where the shape is not an object literal the
+     * inspector can read — a shared const, a union, a non-zod vendor.
+     */
+    props?: Record<string, string>;
+}
+/** Declared analytics events, keyed by event name. */
+export type AnalyticsEventsMeta = Record<string, AnalyticsEventMeta>;

package/dist/analytics/analytics.types.js

@@ -0,0 +1 @@
+export {};

package/dist/analytics/anonymous-analytics-identity.d.ts

@@ -0,0 +1,23 @@
+import type { SerializeOptions } from 'cookie';
+import type { AnalyticsIdentityResolver } from './analytics.types.js';
+export interface AnonymousAnalyticsIdentityOptions {
+    /** Cookie name. Defaults to `pikku_aid`. */
+    name?: string;
+    /**
+     * Consent purposes required before the cookie is written. Storing an
+     * analytics id on someone's device is the act consent governs, so this is
+     * usually set — and left unset only where the deployment meets a regulator's
+     * exemption for strictly necessary audience measurement.
+     */
+    requires?: string[];
+    cookie?: SerializeOptions;
+}
+/**
+ * Mints a device-scoped id for visitors who have no session yet.
+ *
+ * `httpOnly` by default, which is the honest reading of what this is for: no
+ * browser script needs it, and a cookie scripts cannot touch is both harder to
+ * misuse and not subject to the seven-day cap browsers place on script-set
+ * ones. An app that wants a vendor SDK to read it must opt out deliberately.
+ */
+export declare const anonymousAnalyticsIdentity: (options?: AnonymousAnalyticsIdentityOptions) => AnalyticsIdentityResolver;

package/dist/analytics/anonymous-analytics-identity.js

@@ -0,0 +1,27 @@
+import { mintCookie } from './mint-cookie.js';
+const TWO_YEARS_SECONDS = 63_072_000;
+const DEFAULT_COOKIE = {
+    path: '/',
+    maxAge: TWO_YEARS_SECONDS,
+    sameSite: 'lax',
+    httpOnly: true,
+    secure: true,
+};
+/**
+ * Mints a device-scoped id for visitors who have no session yet.
+ *
+ * `httpOnly` by default, which is the honest reading of what this is for: no
+ * browser script needs it, and a cookie scripts cannot touch is both harder to
+ * misuse and not subject to the seven-day cap browsers place on script-set
+ * ones. An app that wants a vendor SDK to read it must opt out deliberately.
+ */
+export const anonymousAnalyticsIdentity = (options = {}) => {
+    return (wire, resolved) => {
+        const anonymousId = mintCookie(wire, options.name ?? 'pikku_aid', {
+            cookie: { ...DEFAULT_COOKIE, ...options.cookie },
+            requires: options.requires,
+            consent: resolved?.consent,
+        }, () => crypto.randomUUID());
+        return anonymousId === undefined ? undefined : { anonymousId };
+    };
+};

package/dist/analytics/compose-analytics-identity.d.ts

@@ -0,0 +1,14 @@
+import type { AnalyticsIdentityResolver } from './analytics.types.js';
+/**
+ * Runs resolvers in order, each seeing what the ones before it produced.
+ *
+ * Order is meaningful rather than incidental: a resolver that mints a cookie
+ * may only do so once consent has been read, so the resolver reading consent
+ * has to come first. Put the other way round, the minter sees no consent, mints
+ * nothing, and the app collects nothing — silently, which is why this threads
+ * state through instead of merging independent results.
+ *
+ * A later resolver wins a key it sets, so a minter's freshly created id
+ * replaces the absent one the cookie reader could not find.
+ */
+export declare const composeAnalyticsIdentity: (...resolvers: AnalyticsIdentityResolver[]) => AnalyticsIdentityResolver;