aimeat 3.1.0 → 3.3.0

package/dist/src/storage/providers/postgres-kysely/methods/usage.js

@@ -0,0 +1,336 @@
+/**
+ * @file src/storage/providers/postgres-kysely/methods/usage.ts
+ * @description Postgres implementation of usage telemetry's three layers: the hot call stream, the
+ *   archive sweep, and the discriminated serving rollup with its transactional fold.
+ *   Design: docs/internal/telemetria/02-design.md
+ *
+ *   BIGINT ARRIVES AS A STRING. node-postgres returns int8 as text to avoid silent precision loss,
+ *   so every metric read goes through `num()`. Reading them raw would put "42" where 42 belongs and
+ *   turn a sum into concatenation, which is exactly the kind of defect a chart makes look plausible.
+ * @structure
+ *   - usageMethods.appendUsageCall / listUsageCalls / *ForFold
+ *   - usageMethods.archiveUsageRows
+ *   - usageMethods.getUsageCursor / setUsageCursor / advanceUsageRollup
+ *   - usageMethods.queryUsageRollup / clearUsageRollupRange
+ * @usage Object.assign(PostgresKyselyStorage.prototype, usageMethods) in ../index.ts
+ * @version-history
+ *   v1.0.0 — 2026-08-14 — Initial: three-layer usage telemetry substrate.
+ */
+import { randomUUID } from 'node:crypto';
+import { sql } from 'kysely';
+/** int8 comes back as a string; anything unparseable is 0 rather than NaN reaching a chart. */
+function num(v) {
+    if (typeof v === 'number')
+        return Number.isFinite(v) ? v : 0;
+    if (typeof v === 'bigint')
+        return Number(v);
+    if (typeof v === 'string') {
+        const n = Number(v);
+        return Number.isFinite(n) ? n : 0;
+    }
+    return 0;
+}
+function obj(v) {
+    return v && typeof v === 'object' && !Array.isArray(v) ? v : {};
+}
+function numObj(v) {
+    const out = {};
+    for (const [k, val] of Object.entries(obj(v)))
+        out[k] = num(val);
+    return out;
+}
+function toCall(r) {
+    return {
+        id: r.id,
+        ts: r.ts,
+        ownerGhii: r.ownerGhii,
+        actorGaii: r.actorGaii ?? '',
+        actorKind: (r.actorKind || 'owner'),
+        surface: r.surface,
+        coordinate: r.coordinate ?? '',
+        appId: r.appId ?? '',
+        counterpartyGhii: r.counterpartyGhii ?? '',
+        outcome: (r.outcome || 'ok'),
+        reason: r.reason ?? '',
+        durationMs: num(r.durationMs),
+        chargedUnits: num(r.chargedUnits),
+        unit: (r.unit ?? ''),
+        currency: r.currency ?? '',
+        entitlementId: r.entitlementId ?? '',
+        runId: r.runId ?? '',
+        meta: obj(r.meta),
+    };
+}
+function toRollup(r) {
+    return {
+        id: r.id,
+        cut: r.cut,
+        grain: r.grain,
+        bucket: r.bucket,
+        ownerGhii: r.ownerGhii ?? '',
+        actorGaii: r.actorGaii ?? '',
+        appId: r.appId ?? '',
+        model: r.model ?? '',
+        provider: r.provider ?? '',
+        surface: r.surface ?? '',
+        outcome: r.outcome ?? '',
+        coordinate: r.coordinate ?? '',
+        counterpartyGhii: r.counterpartyGhii ?? '',
+        calls: num(r.calls),
+        errors: num(r.errors),
+        refusals: num(r.refusals),
+        tokensIn: num(r.tokensIn),
+        tokensOut: num(r.tokensOut),
+        costUsd: num(r.costUsd),
+        unpricedCalls: num(r.unpricedCalls),
+        chargedUnits: num(r.chargedUnits),
+        durationMsSum: num(r.durationMsSum),
+        durationMsMax: num(r.durationMsMax),
+        actorsSeen: num(r.actorsSeen),
+        extra: numObj(r.extra),
+        updatedAt: r.updatedAt,
+    };
+}
+/** The LLM-ledger row shape the fold consumes. Kept local — the ledger's own mapper is private. */
+function toEvent(r) {
+    return {
+        id: r.id,
+        ts: r.ts,
+        agentGaii: r.agentGaii,
+        ownerGhii: r.ownerGhii,
+        runId: r.runId ?? undefined,
+        model: r.model,
+        provider: r.provider,
+        promptTokens: num(r.promptTokens),
+        completionTokens: num(r.completionTokens),
+        costUsd: r.costUsd == null ? null : num(r.costUsd),
+        priceRef: r.priceRef ?? null,
+        source: r.source,
+        apiKeyScope: r.apiKeyScope,
+        organismId: r.organismId ?? undefined,
+        workspaceId: r.workspaceId ?? undefined,
+        capabilityId: r.capabilityId ?? undefined,
+        consumerGhii: r.consumerGhii ?? undefined,
+        provenanceId: r.provenanceId ?? undefined,
+        appId: r.appId ?? '',
+        surface: r.surface ?? '',
+    };
+}
+export const usageMethods = {
+    // ── Layer 1 ──
+    async appendUsageCall(rows) {
+        if (!rows.length)
+            return;
+        await this.db.insertInto('UsageCall').values(rows.map(r => ({
+            id: r.id, ts: r.ts, ownerGhii: r.ownerGhii,
+            actorGaii: r.actorGaii, actorKind: r.actorKind, surface: r.surface,
+            coordinate: r.coordinate, appId: r.appId, counterpartyGhii: r.counterpartyGhii,
+            outcome: r.outcome, reason: r.reason, durationMs: r.durationMs,
+            chargedUnits: r.chargedUnits, unit: r.unit, currency: r.currency,
+            entitlementId: r.entitlementId, runId: r.runId,
+            meta: JSON.stringify(r.meta),
+        }))).execute();
+    },
+    async listUsageCalls(filter) {
+        // NOT owner-scoped unless the filter says so: the route gates this on the operator role and
+        // records its own inspection (design: the audit rule).
+        let q = this.db.selectFrom('UsageCall').selectAll();
+        if (filter.ownerGhii)
+            q = q.where('ownerGhii', '=', filter.ownerGhii);
+        if (filter.actorGaii)
+            q = q.where('actorGaii', '=', filter.actorGaii);
+        if (filter.surface)
+            q = q.where('surface', '=', filter.surface);
+        if (filter.appId)
+            q = q.where('appId', '=', filter.appId);
+        if (filter.outcome)
+            q = q.where('outcome', '=', filter.outcome);
+        if (filter.from)
+            q = q.where('ts', '>=', filter.from);
+        if (filter.to)
+            q = q.where('ts', '<=', filter.to);
+        const limit = Math.min(Math.max(filter.limit ?? 200, 1), 2000);
+        const rows = await q.orderBy('ts', 'desc').limit(limit).execute();
+        return rows.map(r => toCall(r));
+    },
+    async listUsageCallsForFold(c) {
+        // Strictly AFTER (lastTs, lastId) in the stream's total order. A row-value comparison, so the
+        // second field only decides ties — the plain `ts > x OR (ts = x AND id > y)` written out.
+        const rows = await this.db.selectFrom('UsageCall').selectAll()
+            .where(sql `("ts", "id") > (${c.lastTs}, ${c.lastId})`)
+            .orderBy('ts', 'asc').orderBy('id', 'asc')
+            .limit(Math.min(Math.max(c.limit, 1), 20_000))
+            .execute();
+        return rows.map(r => toCall(r));
+    },
+    async listUsageEventsForFold(c) {
+        const rows = await this.db.selectFrom('AgentUsageEvent').selectAll()
+            .where(sql `("ts", "id") > (${c.lastTs}, ${c.lastId})`)
+            .orderBy('ts', 'asc').orderBy('id', 'asc')
+            .limit(Math.min(Math.max(c.limit, 1), 20_000))
+            .execute();
+        return rows.map(r => toEvent(r));
+    },
+    // ── Layer 2 ──
+    async archiveUsageRows(args) {
+        const batch = Math.min(Math.max(args.batch, 1), 20_000);
+        const archivedAt = new Date().toISOString();
+        // INSERT … SELECT then DELETE, per table, inside one transaction each: a crash between the two
+        // halves must not leave a row in both places or in neither. `ON CONFLICT DO NOTHING` makes a
+        // replayed batch idempotent (the id is the archive's primary key too).
+        //
+        // COLUMNS ARE NAMED, not `SELECT *`. A positional copy works until someone ALTERs the hot table,
+        // and then it either fails loudly or, if the new column happens to type-match, writes values
+        // into the wrong columns of a table nobody looks at.
+        const usageCalls = await this.transaction(async () => {
+            const picked = await this.db.selectFrom('UsageCall').select('id')
+                .where('ts', '<', args.before).orderBy('ts', 'asc').limit(batch).execute();
+            const ids = picked.map(p => p.id);
+            if (!ids.length)
+                return 0;
+            await sql `
+        INSERT INTO "UsageCallArchive" (
+          "id","ts","ownerGhii","actorGaii","actorKind","surface","coordinate","appId",
+          "counterpartyGhii","outcome","reason","durationMs","chargedUnits","unit","currency",
+          "entitlementId","runId","meta","archivedAt")
+        SELECT
+          "id","ts","ownerGhii","actorGaii","actorKind","surface","coordinate","appId",
+          "counterpartyGhii","outcome","reason","durationMs","chargedUnits","unit","currency",
+          "entitlementId","runId","meta", ${archivedAt}
+        FROM "UsageCall" WHERE "id" = ANY(${ids})
+        ON CONFLICT ("id") DO NOTHING
+      `.execute(this.db);
+            await this.db.deleteFrom('UsageCall').where('id', 'in', ids).execute();
+            return ids.length;
+        });
+        const usageEvents = await this.transaction(async () => {
+            const picked = await this.db.selectFrom('AgentUsageEvent').select('id')
+                .where('ts', '<', args.before).orderBy('ts', 'asc').limit(batch).execute();
+            const ids = picked.map(p => p.id);
+            if (!ids.length)
+                return 0;
+            await sql `
+        INSERT INTO "AgentUsageEventArchive" (
+          "id","ts","agentGaii","ownerGhii","runId","model","provider","promptTokens",
+          "completionTokens","costUsd","priceRef","source","apiKeyScope","organismId",
+          "workspaceId","capabilityId","consumerGhii","provenanceId","appId","surface","archivedAt")
+        SELECT
+          "id","ts","agentGaii","ownerGhii","runId","model","provider","promptTokens",
+          "completionTokens","costUsd","priceRef","source","apiKeyScope","organismId",
+          "workspaceId","capabilityId","consumerGhii","provenanceId","appId","surface", ${archivedAt}
+        FROM "AgentUsageEvent" WHERE "id" = ANY(${ids})
+        ON CONFLICT ("id") DO NOTHING
+      `.execute(this.db);
+            await this.db.deleteFrom('AgentUsageEvent').where('id', 'in', ids).execute();
+            return ids.length;
+        });
+        // Hour-grain rollups are the live-dashboard resolution and are not kept: the day grain carries
+        // the history. Deleted rather than archived — it is derived data, rebuildable from raw.
+        const pruned = await this.db.deleteFrom('UsageRollup')
+            .where('grain', '=', 'hour').where('bucket', '<', args.pruneHourBefore)
+            .executeTakeFirst();
+        return { usageCalls, usageEvents, hourRollupsPruned: Number(pruned?.numDeletedRows ?? 0) };
+    },
+    async pruneUsageArchive(before) {
+        const calls = await this.db.deleteFrom('UsageCallArchive').where('ts', '<', before).executeTakeFirst();
+        const events = await this.db.deleteFrom('AgentUsageEventArchive').where('ts', '<', before).executeTakeFirst();
+        return {
+            usageCalls: Number(calls?.numDeletedRows ?? 0),
+            usageEvents: Number(events?.numDeletedRows ?? 0),
+        };
+    },
+    // ── Layer 3 ──
+    async getUsageCursor(stream) {
+        const row = await this.db.selectFrom('UsageRollupState').selectAll()
+            .where('stream', '=', stream).executeTakeFirst();
+        if (!row)
+            return null;
+        return { stream, lastTs: row.lastTs, lastId: row.lastId, updatedAt: row.updatedAt };
+    },
+    async setUsageCursor(stream, lastTs, lastId) {
+        const updatedAt = new Date().toISOString();
+        await this.db.insertInto('UsageRollupState')
+            .values({ stream, lastTs, lastId, updatedAt })
+            .onConflict(oc => oc.column('stream').doUpdateSet({ lastTs, lastId, updatedAt }))
+            .execute();
+    },
+    async advanceUsageRollup(args) {
+        const updatedAt = new Date().toISOString();
+        // ONE transaction, and that is the whole exactly-once guarantee. A crash before commit replays
+        // these rows; a crash after commit continues past them. Split the two halves and one of those
+        // outcomes becomes a double count.
+        await this.transaction(async () => {
+            for (const d of args.deltas) {
+                await this.db.insertInto('UsageRollup').values({
+                    id: randomUUID(),
+                    cut: d.cut, grain: d.grain, bucket: d.bucket,
+                    ownerGhii: d.ownerGhii, actorGaii: d.actorGaii, appId: d.appId,
+                    model: d.model, provider: d.provider, surface: d.surface,
+                    outcome: d.outcome, coordinate: d.coordinate, counterpartyGhii: d.counterpartyGhii,
+                    calls: d.calls, errors: d.errors, refusals: d.refusals,
+                    tokensIn: d.tokensIn, tokensOut: d.tokensOut, costUsd: d.costUsd,
+                    unpricedCalls: d.unpricedCalls, chargedUnits: d.chargedUnits,
+                    durationMsSum: d.durationMsSum, durationMsMax: d.durationMsMax,
+                    actorsSeen: d.actorsSeen,
+                    extra: JSON.stringify(d.extra ?? {}),
+                    updatedAt,
+                }).onConflict(oc => oc
+                    .columns(['cut', 'grain', 'bucket', 'ownerGhii', 'actorGaii', 'appId', 'model',
+                    'provider', 'surface', 'outcome', 'coordinate', 'counterpartyGhii'])
+                    .doUpdateSet({
+                    calls: sql `"UsageRollup"."calls" + ${d.calls}`,
+                    errors: sql `"UsageRollup"."errors" + ${d.errors}`,
+                    refusals: sql `"UsageRollup"."refusals" + ${d.refusals}`,
+                    tokensIn: sql `"UsageRollup"."tokensIn" + ${d.tokensIn}`,
+                    tokensOut: sql `"UsageRollup"."tokensOut" + ${d.tokensOut}`,
+                    costUsd: sql `"UsageRollup"."costUsd" + ${d.costUsd}`,
+                    unpricedCalls: sql `"UsageRollup"."unpricedCalls" + ${d.unpricedCalls}`,
+                    chargedUnits: sql `"UsageRollup"."chargedUnits" + ${d.chargedUnits}`,
+                    durationMsSum: sql `"UsageRollup"."durationMsSum" + ${d.durationMsSum}`,
+                    // A maximum is not a sum. This is the one metric that does not add.
+                    durationMsMax: sql `GREATEST("UsageRollup"."durationMsMax", ${d.durationMsMax})`,
+                    actorsSeen: sql `"UsageRollup"."actorsSeen" + ${d.actorsSeen}`,
+                    extra: sql `"UsageRollup"."extra" || ${JSON.stringify(d.extra ?? {})}::jsonb`,
+                    updatedAt,
+                })).execute();
+            }
+            await this.db.insertInto('UsageRollupState')
+                .values({ stream: args.stream, lastTs: args.lastTs, lastId: args.lastId, updatedAt })
+                .onConflict(oc => oc.column('stream')
+                .doUpdateSet({ lastTs: args.lastTs, lastId: args.lastId, updatedAt }))
+                .execute();
+        });
+    },
+    async queryUsageRollup(filter) {
+        let q = this.db.selectFrom('UsageRollup').selectAll().where('cut', '=', filter.cut);
+        if (filter.grain)
+            q = q.where('grain', '=', filter.grain);
+        if (filter.from)
+            q = q.where('bucket', '>=', filter.from);
+        if (filter.to)
+            q = q.where('bucket', '<=', filter.to);
+        if (filter.ownerGhii)
+            q = q.where('ownerGhii', '=', filter.ownerGhii);
+        if (filter.appId)
+            q = q.where('appId', '=', filter.appId);
+        if (filter.actorGaii)
+            q = q.where('actorGaii', '=', filter.actorGaii);
+        if (filter.counterpartyGhii)
+            q = q.where('counterpartyGhii', '=', filter.counterpartyGhii);
+        const limit = Math.min(Math.max(filter.limit ?? 5000, 1), 50_000);
+        const rows = await q.orderBy('bucket', 'asc').limit(limit).execute();
+        return rows.map(r => toRollup(r));
+    },
+    async clearUsageRollupRange(args) {
+        let q = this.db.deleteFrom('UsageRollup');
+        if (args.grain)
+            q = q.where('grain', '=', args.grain);
+        if (args.from)
+            q = q.where('bucket', '>=', args.from);
+        if (args.to)
+            q = q.where('bucket', '<=', args.to);
+        const res = await q.executeTakeFirst();
+        return Number(res?.numDeletedRows ?? 0);
+    },
+};
+//# sourceMappingURL=usage.js.map

package/dist/src/storage/providers/postgres-kysely/methods/usage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.js","sourceRoot":"","sources":["../../../../../../src/storage/providers/postgres-kysely/methods/usage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,GAAG,EAAE,MAAM,QAAQ,CAAC;AAiB7B,+FAA+F;AAC/F,SAAS,GAAG,CAAC,CAAU;IACrB,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC7D,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,MAAM,CAAC,CAAC,CAAC,CAAC;IAC5C,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;QAAC,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;QAAC,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAAC,CAAC;IACtF,OAAO,CAAC,CAAC;AACX,CAAC;AAED,SAAS,GAAG,CAAC,CAAU;IACrB,OAAO,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAE,CAA6B,CAAC,CAAC,CAAC,EAAE,CAAC;AAC/F,CAAC;AAED,SAAS,MAAM,CAAC,CAAU;IACxB,MAAM,GAAG,GAA2B,EAAE,CAAC;IACvC,KAAK,MAAM,CAAC,CAAC,EAAE,GAAG,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QAAE,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;IACjE,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAS,MAAM,CAAC,CAA0B;IACxC,OAAO;QACL,EAAE,EAAE,CAAC,CAAC,EAAY;QAClB,EAAE,EAAE,CAAC,CAAC,EAAY;QAClB,SAAS,EAAE,CAAC,CAAC,SAAmB;QAChC,SAAS,EAAG,CAAC,CAAC,SAAoB,IAAI,EAAE;QACxC,SAAS,EAAE,CAAE,CAAC,CAAC,SAAoB,IAAI,OAAO,CAAmB;QACjE,OAAO,EAAE,CAAC,CAAC,OAAuB;QAClC,UAAU,EAAG,CAAC,CAAC,UAAqB,IAAI,EAAE;QAC1C,KAAK,EAAG,CAAC,CAAC,KAAgB,IAAI,EAAE;QAChC,gBAAgB,EAAG,CAAC,CAAC,gBAA2B,IAAI,EAAE;QACtD,OAAO,EAAE,CAAE,CAAC,CAAC,OAAkB,IAAI,IAAI,CAAiB;QACxD,MAAM,EAAG,CAAC,CAAC,MAAiB,IAAI,EAAE;QAClC,UAAU,EAAE,GAAG,CAAC,CAAC,CAAC,UAAU,CAAC;QAC7B,YAAY,EAAE,GAAG,CAAC,CAAC,CAAC,YAAY,CAAC;QACjC,IAAI,EAAE,CAAE,CAAC,CAAC,IAAe,IAAI,EAAE,CAA4B;QAC3D,QAAQ,EAAG,CAAC,CAAC,QAAmB,IAAI,EAAE;QACtC,aAAa,EAAG,CAAC,CAAC,aAAwB,IAAI,EAAE;QAChD,KAAK,EAAG,CAAC,CAAC,KAAgB,IAAI,EAAE;QAChC,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;KAClB,CAAC;AACJ,CAAC;AAED,SAAS,QAAQ,CAAC,CAA0B;IAC1C,OAAO;QACL,EAAE,EAAE,CAAC,CAAC,EAAY;QAClB,GAAG,EAAE,CAAC,CAAC,GAAa;QACpB,KAAK,EAAE,CAAC,CAAC,KAAuB;QAChC,MAAM,EAAE,CAAC,CAAC,MAAgB;QAC1B,SAAS,EAAG,CAAC,CAAC,SAAoB,IAAI,EAAE;QACxC,SAAS,EAAG,CAAC,CAAC,SAAoB,IAAI,EAAE;QACxC,KAAK,EAAG,CAAC,CAAC,KAAgB,IAAI,EAAE;QAChC,KAAK,EAAG,CAAC,CAAC,KAAgB,IAAI,EAAE;QAChC,QAAQ,EAAG,CAAC,CAAC,QAAmB,IAAI,EAAE;QACtC,OAAO,EAAG,CAAC,CAAC,OAAkB,IAAI,EAAE;QACpC,OAAO,EAAG,CAAC,CAAC,OAAkB,IAAI,EAAE;QACpC,UAAU,EAAG,CAAC,CAAC,UAAqB,IAAI,EAAE;QAC1C,gBAAgB,EAAG,CAAC,CAAC,gBAA2B,IAAI,EAAE;QACtD,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC;QACnB,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC;QACrB,QAAQ,EAAE,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC;QACzB,QAAQ,EAAE,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC;QACzB,SAAS,EAAE,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;QAC3B,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC;QACvB,aAAa,EAAE,GAAG,CAAC,CAAC,CAAC,aAAa,CAAC;QACnC,YAAY,EAAE,GAAG,CAAC,CAAC,CAAC,YAAY,CAAC;QACjC,aAAa,EAAE,GAAG,CAAC,CAAC,CAAC,aAAa,CAAC;QACnC,aAAa,EAAE,GAAG,CAAC,CAAC,CAAC,aAAa,CAAC;QACnC,UAAU,EAAE,GAAG,CAAC,CAAC,CAAC,UAAU,CAAC;QAC7B,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC;QACtB,SAAS,EAAE,CAAC,CAAC,SAAmB;KACjC,CAAC;AACJ,CAAC;AAED,mGAAmG;AACnG,SAAS,OAAO,CAAC,CAA0B;IACzC,OAAO;QACL,EAAE,EAAE,CAAC,CAAC,EAAY;QAClB,EAAE,EAAE,CAAC,CAAC,EAAY;QAClB,SAAS,EAAE,CAAC,CAAC,SAAmB;QAChC,SAAS,EAAE,CAAC,CAAC,SAAmB;QAChC,KAAK,EAAG,CAAC,CAAC,KAAuB,IAAI,SAAS;QAC9C,KAAK,EAAE,CAAC,CAAC,KAAe;QACxB,QAAQ,EAAE,CAAC,CAAC,QAAkB;QAC9B,YAAY,EAAE,GAAG,CAAC,CAAC,CAAC,YAAY,CAAC;QACjC,gBAAgB,EAAE,GAAG,CAAC,CAAC,CAAC,gBAAgB,CAAC;QACzC,OAAO,EAAE,CAAC,CAAC,OAAO,IAAI,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC;QAClD,QAAQ,EAAG,CAAC,CAAC,QAA0B,IAAI,IAAI;QAC/C,MAAM,EAAE,CAAC,CAAC,MAAgB;QAC1B,WAAW,EAAE,CAAC,CAAC,WAA6B;QAC5C,UAAU,EAAG,CAAC,CAAC,UAA4B,IAAI,SAAS;QACxD,WAAW,EAAG,CAAC,CAAC,WAA6B,IAAI,SAAS;QAC1D,YAAY,EAAG,CAAC,CAAC,YAA8B,IAAI,SAAS;QAC5D,YAAY,EAAG,CAAC,CAAC,YAA8B,IAAI,SAAS;QAC5D,YAAY,EAAG,CAAC,CAAC,YAA8B,IAAI,SAAS;QAC5D,KAAK,EAAG,CAAC,CAAC,KAAgB,IAAI,EAAE;QAChC,OAAO,EAAG,CAAC,CAAC,OAAkB,IAAI,EAAE;KACrC,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,gBAAgB;IAEhB,KAAK,CAAC,eAAe,CAA8B,IAAuB;QACxE,IAAI,CAAC,IAAI,CAAC,MAAM;YAAE,OAAO;QACzB,MAAM,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;YAC1D,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC,SAAS;YAC1C,SAAS,EAAE,CAAC,CAAC,SAAS,EAAE,SAAS,EAAE,CAAC,CAAC,SAAS,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO;YAClE,UAAU,EAAE,CAAC,CAAC,UAAU,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,gBAAgB,EAAE,CAAC,CAAC,gBAAgB;YAC9E,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,UAAU,EAAE,CAAC,CAAC,UAAU;YAC9D,YAAY,EAAE,CAAC,CAAC,YAAY,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ;YAChE,aAAa,EAAE,CAAC,CAAC,aAAa,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK;YAC9C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC;SAC7B,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;IACjB,CAAC;IAED,KAAK,CAAC,cAAc,CAA8B,MAAuB;QACvE,4FAA4F;QAC5F,uDAAuD;QACvD,IAAI,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC,SAAS,EAAE,CAAC;QACpD,IAAI,MAAM,CAAC,SAAS;YAAE,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,WAAW,EAAE,GAAG,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC;QACtE,IAAI,MAAM,CAAC,SAAS;YAAE,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,WAAW,EAAE,GAAG,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC;QACtE,IAAI,MAAM,CAAC,OAAO;YAAE,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,SAAS,EAAE,GAAG,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;QAChE,IAAI,MAAM,CAAC,KAAK;YAAE,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,EAAE,GAAG,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;QAC1D,IAAI,MAAM,CAAC,OAAO;YAAE,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,SAAS,EAAE,GAAG,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;QAChE,IAAI,MAAM,CAAC,IAAI;YAAE,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;QACtD,IAAI,MAAM,CAAC,EAAE;YAAE,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;QAClD,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,IAAI,GAAG,EAAE,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;QAC/D,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC;QAClE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,CAAuC,CAAC,CAAC,CAAC;IACxE,CAAC;IAED,KAAK,CAAC,qBAAqB,CAA8B,CAAkB;QACzE,8FAA8F;QAC9F,0FAA0F;QAC1F,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC,SAAS,EAAE;aAC3D,KAAK,CAAC,GAAG,CAAS,mBAAmB,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM,GAAG,CAAC;aAC9D,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC;aACzC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;aAC7C,OAAO,EAAE,CAAC;QACb,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,CAAuC,CAAC,CAAC,CAAC;IACxE,CAAC;IAED,KAAK,CAAC,sBAAsB,CAA8B,CAAkB;QAC1E,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,iBAAiB,CAAC,CAAC,SAAS,EAAE;aACjE,KAAK,CAAC,GAAG,CAAS,mBAAmB,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM,GAAG,CAAC;aAC9D,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC;aACzC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;aAC7C,OAAO,EAAE,CAAC;QACb,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,CAAuC,CAAC,CAAC,CAAC;IACzE,CAAC;IAED,gBAAgB;IAEhB,KAAK,CAAC,gBAAgB,CAEpB,IAAgE;QAEhE,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;QACxD,MAAM,UAAU,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QAE5C,+FAA+F;QAC/F,6FAA6F;QAC7F,uEAAuE;QACvE,EAAE;QACF,iGAAiG;QACjG,6FAA6F;QAC7F,qDAAqD;QACrD,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,KAAK,IAAI,EAAE;YACnD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC;iBAC9D,KAAK,CAAC,IAAI,EAAE,GAAG,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC;YAC7E,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;YAClC,IAAI,CAAC,GAAG,CAAC,MAAM;gBAAE,OAAO,CAAC,CAAC;YAC1B,MAAM,GAAG,CAAA;;;;;;;;4CAQ6B,UAAU;4CACV,GAAG;;OAExC,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACnB,MAAM,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC,OAAO,EAAE,CAAC;YACvE,OAAO,GAAG,CAAC,MAAM,CAAC;QACpB,CAAC,CAAC,CAAC;QAEH,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,KAAK,IAAI,EAAE;YACpD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,iBAAiB,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC;iBACpE,KAAK,CAAC,IAAI,EAAE,GAAG,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC;YAC7E,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;YAClC,IAAI,CAAC,GAAG,CAAC,MAAM;gBAAE,OAAO,CAAC,CAAC;YAC1B,MAAM,GAAG,CAAA;;;;;;;;0FAQ2E,UAAU;kDAClD,GAAG;;OAE9C,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACnB,MAAM,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,iBAAiB,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC,OAAO,EAAE,CAAC;YAC7E,OAAO,GAAG,CAAC,MAAM,CAAC;QACpB,CAAC,CAAC,CAAC;QAEH,+FAA+F;QAC/F,wFAAwF;QACxF,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,aAAa,CAAC;aACnD,KAAK,CAAC,OAAO,EAAE,GAAG,EAAE,MAAM,CAAC,CAAC,KAAK,CAAC,QAAQ,EAAE,GAAG,EAAE,IAAI,CAAC,eAAe,CAAC;aACtE,gBAAgB,EAAE,CAAC;QAEtB,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,IAAI,CAAC,CAAC,EAAE,CAAC;IAC7F,CAAC;IAED,KAAK,CAAC,iBAAiB,CACQ,MAAc;QAE3C,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,kBAAkB,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,GAAG,EAAE,MAAM,CAAC,CAAC,gBAAgB,EAAE,CAAC;QACvG,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,wBAAwB,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,GAAG,EAAE,MAAM,CAAC,CAAC,gBAAgB,EAAE,CAAC;QAC9G,OAAO;YACL,UAAU,EAAE,MAAM,CAAC,KAAK,EAAE,cAAc,IAAI,CAAC,CAAC;YAC9C,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,IAAI,CAAC,CAAC;SACjD,CAAC;IACJ,CAAC;IAED,gBAAgB;IAEhB,KAAK,CAAC,cAAc,CAA8B,MAAsB;QACtE,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,kBAAkB,CAAC,CAAC,SAAS,EAAE;aACjE,KAAK,CAAC,QAAQ,EAAE,GAAG,EAAE,MAAM,CAAC,CAAC,gBAAgB,EAAE,CAAC;QACnD,IAAI,CAAC,GAAG;YAAE,OAAO,IAAI,CAAC;QACtB,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,CAAC,SAAS,EAAE,CAAC;IACtF,CAAC;IAED,KAAK,CAAC,cAAc,CAA8B,MAAsB,EAAE,MAAc,EAAE,MAAc;QACtG,MAAM,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QAC3C,MAAM,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,kBAAkB,CAAC;aACzC,MAAM,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;aAC7C,UAAU,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,WAAW,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC;aAChF,OAAO,EAAE,CAAC;IACf,CAAC;IAED,KAAK,CAAC,kBAAkB,CAEtB,IAA4F;QAE5F,MAAM,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QAC3C,+FAA+F;QAC/F,8FAA8F;QAC9F,mCAAmC;QACnC,MAAM,IAAI,CAAC,WAAW,CAAC,KAAK,IAAI,EAAE;YAChC,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;gBAC5B,MAAM,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC,MAAM,CAAC;oBAC7C,EAAE,EAAE,UAAU,EAAE;oBAChB,GAAG,EAAE,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM;oBAC5C,SAAS,EAAE,CAAC,CAAC,SAAS,EAAE,SAAS,EAAE,CAAC,CAAC,SAAS,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK;oBAC9D,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO;oBACxD,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,UAAU,EAAE,CAAC,CAAC,UAAU,EAAE,gBAAgB,EAAE,CAAC,CAAC,gBAAgB;oBAClF,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ;oBACtD,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE,SAAS,EAAE,CAAC,CAAC,SAAS,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO;oBAChE,aAAa,EAAE,CAAC,CAAC,aAAa,EAAE,YAAY,EAAE,CAAC,CAAC,YAAY;oBAC5D,aAAa,EAAE,CAAC,CAAC,aAAa,EAAE,aAAa,EAAE,CAAC,CAAC,aAAa;oBAC9D,UAAU,EAAE,CAAC,CAAC,UAAU;oBACxB,KAAK,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;oBACpC,SAAS;iBACV,CAAC,CAAC,UAAU,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE;qBACnB,OAAO,CAAC,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,WAAW,EAAE,OAAO,EAAE,OAAO;oBACpE,UAAU,EAAE,SAAS,EAAE,SAAS,EAAE,YAAY,EAAE,kBAAkB,CAAC,CAAC;qBAC7E,WAAW,CAAC;oBACX,KAAK,EAAE,GAAG,CAAA,2BAA2B,CAAC,CAAC,KAAK,EAAE;oBAC9C,MAAM,EAAE,GAAG,CAAA,4BAA4B,CAAC,CAAC,MAAM,EAAE;oBACjD,QAAQ,EAAE,GAAG,CAAA,8BAA8B,CAAC,CAAC,QAAQ,EAAE;oBACvD,QAAQ,EAAE,GAAG,CAAA,8BAA8B,CAAC,CAAC,QAAQ,EAAE;oBACvD,SAAS,EAAE,GAAG,CAAA,+BAA+B,CAAC,CAAC,SAAS,EAAE;oBAC1D,OAAO,EAAE,GAAG,CAAA,6BAA6B,CAAC,CAAC,OAAO,EAAE;oBACpD,aAAa,EAAE,GAAG,CAAA,mCAAmC,CAAC,CAAC,aAAa,EAAE;oBACtE,YAAY,EAAE,GAAG,CAAA,kCAAkC,CAAC,CAAC,YAAY,EAAE;oBACnE,aAAa,EAAE,GAAG,CAAA,mCAAmC,CAAC,CAAC,aAAa,EAAE;oBACtE,oEAAoE;oBACpE,aAAa,EAAE,GAAG,CAAA,2CAA2C,CAAC,CAAC,aAAa,GAAG;oBAC/E,UAAU,EAAE,GAAG,CAAA,gCAAgC,CAAC,CAAC,UAAU,EAAE;oBAC7D,KAAK,EAAE,GAAG,CAAA,4BAA4B,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC,SAAS;oBAC5E,SAAS;iBACV,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;YAClB,CAAC;YACD,MAAM,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,kBAAkB,CAAC;iBACzC,MAAM,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,SAAS,EAAE,CAAC;iBACpF,UAAU,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC;iBAClC,WAAW,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC;iBACvE,OAAO,EAAE,CAAC;QACf,CAAC,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,gBAAgB,CAA8B,MAAyB;QAC3E,IAAI,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC,SAAS,EAAE,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;QACpF,IAAI,MAAM,CAAC,KAAK;YAAE,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,EAAE,GAAG,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;QAC1D,IAAI,MAAM,CAAC,IAAI;YAAE,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,QAAQ,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;QAC1D,IAAI,MAAM,CAAC,EAAE;YAAE,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,QAAQ,EAAE,IAAI,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;QACtD,IAAI,MAAM,CAAC,SAAS;YAAE,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,WAAW,EAAE,GAAG,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC;QACtE,IAAI,MAAM,CAAC,KAAK;YAAE,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,EAAE,GAAG,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;QAC1D,IAAI,MAAM,CAAC,SAAS;YAAE,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,WAAW,EAAE,GAAG,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC;QACtE,IAAI,MAAM,CAAC,gBAAgB;YAAE,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,kBAAkB,EAAE,GAAG,EAAE,MAAM,CAAC,gBAAgB,CAAC,CAAC;QAC3F,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,IAAI,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;QAClE,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC;QACrE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,QAAQ,CAAC,CAAuC,CAAC,CAAC,CAAC;IAC1E,CAAC;IAED,KAAK,CAAC,qBAAqB,CAEzB,IAA4D;QAE5D,IAAI,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;QAC1C,IAAI,IAAI,CAAC,KAAK;YAAE,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,EAAE,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;QACtD,IAAI,IAAI,CAAC,IAAI;YAAE,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,QAAQ,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;QACtD,IAAI,IAAI,CAAC,EAAE;YAAE,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,QAAQ,EAAE,IAAI,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC;QAClD,MAAM,GAAG,GAAG,MAAM,CAAC,CAAC,gBAAgB,EAAE,CAAC;QACvC,OAAO,MAAM,CAAC,GAAG,EAAE,cAAc,IAAI,CAAC,CAAC,CAAC;IAC1C,CAAC;CACF,CAAC"}

package/dist/src/storage/providers/postgres-kysely/migrations/0036_usage_telemetry.sql

@@ -0,0 +1,181 @@
+-- 0036_usage_telemetry.sql
+--
+-- Usage telemetry, three layers. Design: docs/internal/telemetria/02-design.md
+--
+--   LAYER 1, hot raw    UsageCall + the existing AgentUsageEvent. Append-only, 90 days.
+--   LAYER 2, cold       UsageCallArchive + AgentUsageEventArchive. Storage, never a data source.
+--   LAYER 3, serving    UsageRollup. Everything a dashboard reads, precomputed incrementally.
+--
+-- WHY A DISCRIMINATED ROLLUP RATHER THAN A TABLE PER REPORT. One table per report is fast and
+-- unextendable: each new question costs a migration on both backends. A fully generic
+-- (scope, key, metrics JSONB) table is extendable and unqueryable: a metric inside JSONB cannot be
+-- summed or ordered by in SQL. So: fixed dimension columns, fixed metric columns, and a `cut` naming
+-- which dimensions THIS row is keyed by. A new report is a new cut in rollup-cuts.ts plus a backfill.
+--
+-- '' IS NOT NULL. A dimension outside the cut holds the empty string, so the unique index is total
+-- and the upsert is a plain ON CONFLICT DO UPDATE SET x = x + excluded.x. A nullable dimension would
+-- make the conflict target unreachable, which is the same trap AgentUsageDaily already documents.
+
+-- ── Layer 1: one row per observable call ────────────────────────────────────────────────────────
+-- The point of this table is `outcome` and `reason`. A refused call is the record that a capability
+-- was wanted and not delivered, and before this table that record did not exist anywhere.
+CREATE TABLE IF NOT EXISTS "UsageCall" (
+  "id"               TEXT NOT NULL,
+  "ts"               TEXT NOT NULL,
+  -- The human whose account this belongs to: the payer for a priced call, the app owner's user for
+  -- an app open. Never a bare owner name — always a GHII, so it joins the ledger.
+  "ownerGhii"        TEXT NOT NULL,
+  -- The exact principal: GHII, GAII, GEAI, or an app grant's gaii. ownerGhii answers "whose",
+  -- actorGaii answers "which of theirs".
+  "actorGaii"        TEXT NOT NULL DEFAULT '',
+  "actorKind"        TEXT NOT NULL DEFAULT 'owner',
+  "surface"          TEXT NOT NULL,
+  "coordinate"       TEXT NOT NULL DEFAULT '',
+  "appId"            TEXT NOT NULL DEFAULT '',
+  -- The provider being bought from on an exchange call, and the inspected owner on an operator
+  -- drill — in both cases "the other party to this call".
+  "counterpartyGhii" TEXT NOT NULL DEFAULT '',
+  "outcome"          TEXT NOT NULL DEFAULT 'ok',
+  "reason"           TEXT NOT NULL DEFAULT '',
+  "durationMs"       INTEGER NOT NULL DEFAULT 0,
+  "chargedUnits"     BIGINT NOT NULL DEFAULT 0,
+  "unit"             TEXT NOT NULL DEFAULT '',
+  "currency"         TEXT NOT NULL DEFAULT '',
+  "entitlementId"    TEXT NOT NULL DEFAULT '',
+  "runId"            TEXT NOT NULL DEFAULT '',
+  -- Detail the fold never reads. Anything the rollup aggregates gets a column instead.
+  "meta"             JSONB NOT NULL DEFAULT '{}'::jsonb,
+  CONSTRAINT "UsageCall_pkey" PRIMARY KEY ("id")
+);
+
+-- The fold's cursor. (ts, id) is a total order over the stream, so the watermark can resume exactly.
+CREATE INDEX IF NOT EXISTS "UsageCall_cursor_idx" ON "UsageCall"("ts", "id");
+-- The operator drill and the archive sweep.
+CREATE INDEX IF NOT EXISTS "UsageCall_owner_ts_idx" ON "UsageCall"("ownerGhii", "ts" DESC);
+
+-- ── Layer 1: two dimensions onto the existing LLM ledger ────────────────────────────────────────
+-- Without appId, /v1/ai/complete cannot write into the ledger, which is why app-side model and
+-- provider reporting had no data behind it rather than merely no UI.
+ALTER TABLE "AgentUsageEvent" ADD COLUMN IF NOT EXISTS "appId" TEXT NOT NULL DEFAULT '';
+ALTER TABLE "AgentUsageEvent" ADD COLUMN IF NOT EXISTS "surface" TEXT NOT NULL DEFAULT '';
+CREATE INDEX IF NOT EXISTS "AgentUsageEvent_cursor_idx" ON "AgentUsageEvent"("ts", "id");
+
+-- "AgentUsageDaily" IS DELIBERATELY UNTOUCHED. It is the LIVE counter the daily AI budget and the
+-- threshold alerts read at the metering chokepoint, so it must stay synchronous and it must stay
+-- cheap. Per-app daily totals come from the fold instead (cuts llm.app / llm.owner.app), which costs
+-- no write on the call path. Widening its key would also mean rebuilding the SQLite table, whose
+-- composite PRIMARY KEY cannot take a new column by ALTER.
+
+-- ── Layer 2: archive. Column-identical plus archivedAt. Nothing queries these except an export. ──
+CREATE TABLE IF NOT EXISTS "UsageCallArchive" (
+  "id"               TEXT NOT NULL,
+  "ts"               TEXT NOT NULL,
+  "ownerGhii"        TEXT NOT NULL,
+  "actorGaii"        TEXT NOT NULL DEFAULT '',
+  "actorKind"        TEXT NOT NULL DEFAULT 'owner',
+  "surface"          TEXT NOT NULL,
+  "coordinate"       TEXT NOT NULL DEFAULT '',
+  "appId"            TEXT NOT NULL DEFAULT '',
+  "counterpartyGhii" TEXT NOT NULL DEFAULT '',
+  "outcome"          TEXT NOT NULL DEFAULT 'ok',
+  "reason"           TEXT NOT NULL DEFAULT '',
+  "durationMs"       INTEGER NOT NULL DEFAULT 0,
+  "chargedUnits"     BIGINT NOT NULL DEFAULT 0,
+  "unit"             TEXT NOT NULL DEFAULT '',
+  "currency"         TEXT NOT NULL DEFAULT '',
+  "entitlementId"    TEXT NOT NULL DEFAULT '',
+  "runId"            TEXT NOT NULL DEFAULT '',
+  "meta"             JSONB NOT NULL DEFAULT '{}'::jsonb,
+  "archivedAt"       TEXT NOT NULL,
+  CONSTRAINT "UsageCallArchive_pkey" PRIMARY KEY ("id")
+);
+CREATE INDEX IF NOT EXISTS "UsageCallArchive_owner_ts_idx" ON "UsageCallArchive"("ownerGhii", "ts");
+
+CREATE TABLE IF NOT EXISTS "AgentUsageEventArchive" (
+  "id"               TEXT NOT NULL,
+  "ts"               TEXT NOT NULL,
+  "agentGaii"        TEXT NOT NULL,
+  "ownerGhii"        TEXT NOT NULL,
+  "runId"            TEXT,
+  "model"            TEXT NOT NULL,
+  "provider"         TEXT NOT NULL,
+  "promptTokens"     INTEGER NOT NULL DEFAULT 0,
+  "completionTokens" INTEGER NOT NULL DEFAULT 0,
+  "costUsd"          DOUBLE PRECISION,
+  "priceRef"         TEXT,
+  "source"           TEXT NOT NULL,
+  "apiKeyScope"      TEXT NOT NULL DEFAULT 'own',
+  "organismId"       TEXT,
+  "workspaceId"      TEXT,
+  "capabilityId"     TEXT,
+  "consumerGhii"     TEXT,
+  "provenanceId"     TEXT,
+  "appId"            TEXT NOT NULL DEFAULT '',
+  "surface"          TEXT NOT NULL DEFAULT '',
+  "archivedAt"       TEXT NOT NULL,
+  CONSTRAINT "AgentUsageEventArchive_pkey" PRIMARY KEY ("id")
+);
+CREATE INDEX IF NOT EXISTS "AgentUsageEventArchive_owner_ts_idx" ON "AgentUsageEventArchive"("ownerGhii", "ts");
+
+-- ── Layer 3: the one table every dashboard reads ────────────────────────────────────────────────
+CREATE TABLE IF NOT EXISTS "UsageRollup" (
+  "id"               TEXT NOT NULL,
+  -- Which dimension set this row is keyed by, e.g. 'llm.owner.model'. Declared in rollup-cuts.ts.
+  "cut"              TEXT NOT NULL,
+  "grain"            TEXT NOT NULL,
+  -- 'YYYY-MM-DD' at day grain, 'YYYY-MM-DDTHH' at hour grain. Sorts chronologically as text.
+  "bucket"           TEXT NOT NULL,
+
+  -- Dimensions. '' means "not part of this cut", i.e. rolled over.
+  "ownerGhii"        TEXT NOT NULL DEFAULT '',
+  "actorGaii"        TEXT NOT NULL DEFAULT '',
+  "appId"            TEXT NOT NULL DEFAULT '',
+  "model"            TEXT NOT NULL DEFAULT '',
+  "provider"         TEXT NOT NULL DEFAULT '',
+  "surface"          TEXT NOT NULL DEFAULT '',
+  "outcome"          TEXT NOT NULL DEFAULT '',
+  "coordinate"       TEXT NOT NULL DEFAULT '',
+  "counterpartyGhii" TEXT NOT NULL DEFAULT '',
+
+  -- Metrics. Every one of these ADDS on conflict except durationMsMax, which takes the greater.
+  "calls"            BIGINT NOT NULL DEFAULT 0,
+  "errors"           BIGINT NOT NULL DEFAULT 0,
+  "refusals"         BIGINT NOT NULL DEFAULT 0,
+  "tokensIn"         BIGINT NOT NULL DEFAULT 0,
+  "tokensOut"        BIGINT NOT NULL DEFAULT 0,
+  "costUsd"          DOUBLE PRECISION NOT NULL DEFAULT 0,
+  "unpricedCalls"    BIGINT NOT NULL DEFAULT 0,
+  "chargedUnits"     BIGINT NOT NULL DEFAULT 0,
+  "durationMsSum"    BIGINT NOT NULL DEFAULT 0,
+  "durationMsMax"    BIGINT NOT NULL DEFAULT 0,
+  -- Distinct actors within one fold batch, summed across batches: an approximation FROM BELOW.
+  -- Labelled as such wherever it is served, and never used for billing.
+  "actorsSeen"       BIGINT NOT NULL DEFAULT 0,
+
+  -- A future metric that does not deserve a column yet. The fold merges it additively by key.
+  "extra"            JSONB NOT NULL DEFAULT '{}'::jsonb,
+  "updatedAt"        TEXT NOT NULL,
+  CONSTRAINT "UsageRollup_pkey" PRIMARY KEY ("id")
+);
+
+-- The conflict target. Total by construction (no nullable dimension), which is what makes the
+-- upsert-add work at all.
+CREATE UNIQUE INDEX IF NOT EXISTS "UsageRollup_key" ON "UsageRollup"(
+  "cut", "grain", "bucket", "ownerGhii", "actorGaii", "appId", "model", "provider",
+  "surface", "outcome", "coordinate", "counterpartyGhii"
+);
+-- The two read shapes: a whole cut over a range, and one owner's slice of it.
+CREATE INDEX IF NOT EXISTS "UsageRollup_read_idx" ON "UsageRollup"("cut", "grain", "bucket");
+CREATE INDEX IF NOT EXISTS "UsageRollup_owner_idx" ON "UsageRollup"("cut", "ownerGhii", "grain", "bucket");
+
+-- ── The fold's watermark ────────────────────────────────────────────────────────────────────────
+-- One row per raw stream. Advanced in the SAME transaction as the deltas it accounts for, which is
+-- what makes the fold exactly-once: a crash before commit replays those rows, a crash after commit
+-- continues past them, and neither double-counts.
+CREATE TABLE IF NOT EXISTS "UsageRollupState" (
+  "stream"    TEXT NOT NULL,
+  "lastTs"    TEXT NOT NULL DEFAULT '',
+  "lastId"    TEXT NOT NULL DEFAULT '',
+  "updatedAt" TEXT NOT NULL,
+  CONSTRAINT "UsageRollupState_pkey" PRIMARY KEY ("stream")
+);

package/dist/src/storage/providers/postgres-kysely/migrations/0037_task_created_by.sql

@@ -0,0 +1,18 @@
+-- 0037_task_created_by.sql
+--
+-- Who ordered this task.
+--
+-- The node knew it at write time on every door and stored it nowhere. That was harmless while a
+-- task was something an owner gave their own agent, and stopped being harmless the moment one agent
+-- started commissioning another: `aimeat_task_get` authorises against `agentGaii`, which is the
+-- RECEIVER, so the party that placed a commission could not read it back.
+--
+-- The cost showed up on 2026-08-15. A chat ordered a build from a fleet concierge, the build
+-- produced nothing and said nothing, and the only record of the attempt was invisible to the one
+-- party waiting on it. A published guide's "watch the task until it completes" step was
+-- unexecutable by anyone, and the failure could not be diagnosed from either side.
+--
+-- Null on every task that predates this column, which is why the read rule treats an absent value
+-- as "not yours" rather than as a match.
+
+ALTER TABLE "AgentTask" ADD COLUMN IF NOT EXISTS "createdBy" TEXT;

package/dist/src/storage/providers/postgres-kysely/migrations/0038_organism_owners.sql

@@ -0,0 +1,31 @@
+-- 0038_organism_owners.sql
+--
+-- An organism had one owner, and the column holding them held two different facts.
+--
+-- `creatorGhii` answered both "who made this" and "who holds this". The first is history and cannot
+-- change; the second is a role, and a role that only one account can hold has no way back when that
+-- account becomes unreachable. A handover wrote the single column, so moving authority also rewrote
+-- the past: this node's own development organism spent a month claiming it was created by an account
+-- that joined it five weeks after it existed.
+--
+-- Splitting them costs two columns.
+--
+--   createdBy — immutable. A handover never touches it again.
+--   owners    — the authority, plural. Never empty; the last owner cannot be removed, only replaced.
+--
+-- BACKFILL. Both start from `creatorGhii`, because it is the only answer the node ever recorded.
+-- For `owners` that is exactly right. For `createdBy` it is right on every organism that never
+-- changed hands, and wrong on the ones that did — there is no record of who held it before a
+-- handover, so this backfill cannot recover it. The alternative, leaving the column null, would put
+-- the same wrong answer in front of every reader anyway (`createdBy ?? creatorGhii`) while also
+-- losing the ones it gets right. Where the true creator is known it is corrected by hand.
+--
+-- `creatorGhii` stays, as a MIRROR of owners[0] maintained by services/organism-ownership.ts, so
+-- federation payloads, exports and v4 clients keep reading a field that is still true. It is
+-- deprecated as of 2026-08-15 and removed in v5.0; nothing new should compare against it.
+
+ALTER TABLE "Organism" ADD COLUMN IF NOT EXISTS "createdBy" TEXT;
+ALTER TABLE "Organism" ADD COLUMN IF NOT EXISTS "owners" TEXT[];
+
+UPDATE "Organism" SET "createdBy" = "creatorGhii" WHERE "createdBy" IS NULL;
+UPDATE "Organism" SET "owners" = ARRAY["creatorGhii"] WHERE "owners" IS NULL OR cardinality("owners") = 0;

package/dist/src/storage/providers/postgres-kysely/migrations/0039_storage_file_utf8_verified.sql

@@ -0,0 +1,19 @@
+-- TARGET-063: record, once per write, whether a stored file's bytes decode as UTF-8.
+--
+-- WHY A COLUMN AND NOT A READ. The served Content-Type of an uploaded text file depends on a strict
+-- UTF-8 decode of the WHOLE file, and until now every response ran that decode: it needed the bytes,
+-- so it read them. Serving a byte range is where that design breaks, because not reading the file is
+-- the entire point of a range. Measured on this backend: an 8-byte suffix range out of a 25 MB file
+-- costs 181 ms as a whole-row read and 3 ms as a database-side substring. The decode belongs on the
+-- write, where the bytes are already in hand and the answer is a property of the file.
+--
+-- NO BACKFILL, DELIBERATELY. There is no UTF-8 validity predicate in SQL that does not raise on the
+-- first bad byte and take the whole UPDATE with it (convert_from raises; pg_input_is_valid does not
+-- cover bytea to text). So existing rows keep NULL, and a range read of one loads the file exactly
+-- as it does today — the same header, the same cost, no guess. Each row settles itself the next time
+-- it is written. Nothing published after this migration is affected, which is the case that matters.
+--
+-- NULL means "not established", never "not UTF-8". utils/app-content-type.ts treats the two the same
+-- way on purpose: both say nothing about the charset and serve the file as it is served today.
+
+ALTER TABLE "StorageFile" ADD COLUMN IF NOT EXISTS "utf8Verified" BOOLEAN;

package/dist/src/storage/providers/sqlite/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/storage/providers/sqlite/index.ts"],"names":[],"mappings":"AAkCA,OAAO,QAAQ,MAAM,gBAAgB,CAAC;AAGtC,OAAO,KAAK,EAAE,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAGvE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AA6B7D,qBAAa,aAAa;IACxB,EAAE,EAAE,QAAQ,CAAC,QAAQ,CAAC;IACtB,cAAc,mCAA0C;IAExD;;;;OAIG;IACH,OAAO,CAAC,OAAO,CAAK;IACpB;;;OAGG;IACH,OAAO,CAAC,OAAO,CAAuC;gBAE1C,MAAM,EAAE,MAAM;IAS1B;;;;OAIG;IACH,IAAI,iBAAiB,IAAI,OAAO,CAE/B;IAED,gGAAgG;IAChG,oBAAoB,IAAI,OAAO,CAAC,OAAO,CAAC;IAIxC;;;;;OAKG;IACG,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAyBtD,oCAAoC;IACpC,KAAK,IAAI,IAAI;CAGd;AAgCD,MAAM,WAAW,aAAc,SAAQ,OAAO,EAAE,eAAe;CAAG"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/storage/providers/sqlite/index.ts"],"names":[],"mappings":"AAkCA,OAAO,QAAQ,MAAM,gBAAgB,CAAC;AAGtC,OAAO,KAAK,EAAE,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAGvE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AA+B7D,qBAAa,aAAa;IACxB,EAAE,EAAE,QAAQ,CAAC,QAAQ,CAAC;IACtB,cAAc,mCAA0C;IAExD;;;;OAIG;IACH,OAAO,CAAC,OAAO,CAAK;IACpB;;;OAGG;IACH,OAAO,CAAC,OAAO,CAAuC;gBAE1C,MAAM,EAAE,MAAM;IAS1B;;;;OAIG;IACH,IAAI,iBAAiB,IAAI,OAAO,CAE/B;IAED,gGAAgG;IAChG,oBAAoB,IAAI,OAAO,CAAC,OAAO,CAAC;IAIxC;;;;;OAKG;IACG,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAyBtD,oCAAoC;IACpC,KAAK,IAAI,IAAI;CAGd;AAgCD,MAAM,WAAW,aAAc,SAAQ,OAAO,EAAE,eAAe;CAAG"}