@lssm/lib.metering 0.0.0-canary-20251217063201 → 0.0.0-canary-20251217073102

package/dist/aggregation/index.js

@@ -1 +1,271 @@
-function e(e,t){let n=new Date(e);switch(t){case`HOURLY`:return n.setMinutes(0,0,0),n;case`DAILY`:return n.setHours(0,0,0,0),n;case`WEEKLY`:n.setHours(0,0,0,0);let e=n.getDay();return n.setDate(n.getDate()-e),n;case`MONTHLY`:return n.setHours(0,0,0,0),n.setDate(1),n;case`YEARLY`:return n.setHours(0,0,0,0),n.setMonth(0,1),n}}function t(t,n){let r=e(t,n);switch(n){case`HOURLY`:return new Date(r.getTime()+3600*1e3);case`DAILY`:return new Date(r.getTime()+1440*60*1e3);case`WEEKLY`:return new Date(r.getTime()+10080*60*1e3);case`MONTHLY`:{let e=new Date(r);return e.setMonth(e.getMonth()+1),e}case`YEARLY`:{let e=new Date(r);return e.setFullYear(e.getFullYear()+1),e}}}function n(t,n){let i=e(t,n),a=i.getFullYear(),o=String(i.getMonth()+1).padStart(2,`0`),s=String(i.getDate()).padStart(2,`0`),c=String(i.getHours()).padStart(2,`0`);switch(n){case`HOURLY`:return`${a}-${o}-${s}T${c}`;case`DAILY`:return`${a}-${o}-${s}`;case`WEEKLY`:return`${a}-W${r(i)}`;case`MONTHLY`:return`${a}-${o}`;case`YEARLY`:return`${a}`}}function r(e){let t=new Date(Date.UTC(e.getFullYear(),e.getMonth(),e.getDate())),n=t.getUTCDay()||7;t.setUTCDate(t.getUTCDate()+4-n);let r=new Date(Date.UTC(t.getUTCFullYear(),0,1)),i=Math.ceil(((t.getTime()-r.getTime())/864e5+1)/7);return String(i).padStart(2,`0`)}var i=class{storage;batchSize;constructor(e){this.storage=e.storage,this.batchSize=e.batchSize||1e3}async aggregate(e){let{periodType:n,periodStart:r,metricKey:i}=e,a=e.periodEnd||t(r,n),o={periodType:n,periodStart:r,periodEnd:a,recordsProcessed:0,summariesCreated:0,summariesUpdated:0,errors:[]},s=await this.storage.getUnaggregatedRecords({metricKey:i,periodStart:r,periodEnd:a,limit:this.batchSize});if(s.length===0)return o;let c=this.groupRecords(s,n);for(let[e,t]of c.entries())try{await this.aggregateGroup(e,t,n,o)}catch(t){let[n,r,i]=e.split(`::`);o.errors.push({metricKey:n,subjectType:r,subjectId:i,error:t instanceof Error?t.message:String(t)})}let l=s.map(e=>e.id);return await this.storage.markRecordsAggregated(l,new Date),o.recordsProcessed=s.length,o}groupRecords(e,t){let r=new Map;for(let i of e){let e=n(i.timestamp,t),a=`${i.metricKey}::${i.subjectType}::${i.subjectId}::${e}`,o=r.get(a)||[];o.push(i),r.set(a,o)}return r}async aggregateGroup(n,r,i,a){let[o,s,c]=n.split(`::`);if(!o||!s||!c||r.length===0)return;let l=r[0],u=e(l.timestamp,i),d=t(l.timestamp,i),f=(await this.storage.getMetric(o))?.aggregationType||`SUM`,p=r.map(e=>e.quantity),m=this.calculateAggregation(p,f);await this.storage.upsertSummary({metricKey:o,subjectType:s,subjectId:c,periodType:i,periodStart:u,periodEnd:d,totalQuantity:m.total,recordCount:r.length,minQuantity:m.min,maxQuantity:m.max,avgQuantity:m.avg}),a.summariesCreated++}calculateAggregation(e,t){if(e.length===0)return{total:0,min:0,max:0,avg:0};let n=Math.min(...e),r=Math.max(...e),i=e.reduce((e,t)=>e+t,0),a=i/e.length,o=e.length,s;switch(t){case`COUNT`:s=o;break;case`SUM`:s=i;break;case`AVG`:s=a;break;case`MAX`:s=r;break;case`MIN`:s=n;break;case`LAST`:s=e[e.length-1]??0;break;default:s=i}return{total:s,min:n,max:r,avg:a}}},a=class{records=[];summaries=new Map;metrics=new Map;addRecord(e){this.records.push(e)}addMetric(e){this.metrics.set(e.key,e)}async getUnaggregatedRecords(e){let t=this.records.filter(t=>{let n=t.timestamp>=e.periodStart&&t.timestamp<e.periodEnd,r=!e.metricKey||t.metricKey===e.metricKey;return n&&r});return e.limit&&(t=t.slice(0,e.limit)),t}async markRecordsAggregated(e){this.records=this.records.filter(t=>!e.includes(t.id))}async upsertSummary(e){let t=`${e.metricKey}::${e.subjectType}::${e.subjectId}::${e.periodType}::${e.periodStart.toISOString()}`,n=this.summaries.get(t);if(n)return n.totalQuantity+=e.totalQuantity,n.recordCount+=e.recordCount,e.minQuantity!==void 0&&(n.minQuantity=Math.min(n.minQuantity??1/0,e.minQuantity)),e.maxQuantity!==void 0&&(n.maxQuantity=Math.max(n.maxQuantity??-1/0,e.maxQuantity)),n;let r={id:`summary-${Date.now()}-${Math.random().toString(36).slice(2)}`,...e};return this.summaries.set(t,r),r}async getMetric(e){return this.metrics.get(e)||null}async listMetrics(){return Array.from(this.metrics.values())}getSummaries(){return Array.from(this.summaries.values())}clear(){this.records=[],this.summaries.clear(),this.metrics.clear()}};export{a as InMemoryUsageStorage,i as UsageAggregator,n as formatPeriodKey,t as getPeriodEnd,e as getPeriodStart};
+//#region src/aggregation/index.ts
+/**
+* Get the start of a period for a given date.
+*/
+function getPeriodStart(date, periodType) {
+	const d = new Date(date);
+	switch (periodType) {
+		case "HOURLY":
+			d.setMinutes(0, 0, 0);
+			return d;
+		case "DAILY":
+			d.setHours(0, 0, 0, 0);
+			return d;
+		case "WEEKLY":
+			d.setHours(0, 0, 0, 0);
+			const day = d.getDay();
+			d.setDate(d.getDate() - day);
+			return d;
+		case "MONTHLY":
+			d.setHours(0, 0, 0, 0);
+			d.setDate(1);
+			return d;
+		case "YEARLY":
+			d.setHours(0, 0, 0, 0);
+			d.setMonth(0, 1);
+			return d;
+	}
+}
+/**
+* Get the end of a period for a given date.
+*/
+function getPeriodEnd(date, periodType) {
+	const start = getPeriodStart(date, periodType);
+	switch (periodType) {
+		case "HOURLY": return new Date(start.getTime() + 3600 * 1e3);
+		case "DAILY": return new Date(start.getTime() + 1440 * 60 * 1e3);
+		case "WEEKLY": return new Date(start.getTime() + 10080 * 60 * 1e3);
+		case "MONTHLY": {
+			const end = new Date(start);
+			end.setMonth(end.getMonth() + 1);
+			return end;
+		}
+		case "YEARLY": {
+			const end = new Date(start);
+			end.setFullYear(end.getFullYear() + 1);
+			return end;
+		}
+	}
+}
+/**
+* Format a period key for grouping.
+*/
+function formatPeriodKey(date, periodType) {
+	const start = getPeriodStart(date, periodType);
+	const year = start.getFullYear();
+	const month = String(start.getMonth() + 1).padStart(2, "0");
+	const day = String(start.getDate()).padStart(2, "0");
+	const hour = String(start.getHours()).padStart(2, "0");
+	switch (periodType) {
+		case "HOURLY": return `${year}-${month}-${day}T${hour}`;
+		case "DAILY": return `${year}-${month}-${day}`;
+		case "WEEKLY": return `${year}-W${getWeekNumber(start)}`;
+		case "MONTHLY": return `${year}-${month}`;
+		case "YEARLY": return `${year}`;
+	}
+}
+function getWeekNumber(date) {
+	const d = new Date(Date.UTC(date.getFullYear(), date.getMonth(), date.getDate()));
+	const dayNum = d.getUTCDay() || 7;
+	d.setUTCDate(d.getUTCDate() + 4 - dayNum);
+	const yearStart = new Date(Date.UTC(d.getUTCFullYear(), 0, 1));
+	const weekNum = Math.ceil(((d.getTime() - yearStart.getTime()) / 864e5 + 1) / 7);
+	return String(weekNum).padStart(2, "0");
+}
+/**
+* Usage aggregator.
+*
+* Aggregates usage records into summaries based on period type.
+*/
+var UsageAggregator = class {
+	storage;
+	batchSize;
+	constructor(options) {
+		this.storage = options.storage;
+		this.batchSize = options.batchSize || 1e3;
+	}
+	/**
+	* Aggregate usage records for a period.
+	*/
+	async aggregate(params) {
+		const { periodType, periodStart, metricKey } = params;
+		const periodEnd = params.periodEnd || getPeriodEnd(periodStart, periodType);
+		const result = {
+			periodType,
+			periodStart,
+			periodEnd,
+			recordsProcessed: 0,
+			summariesCreated: 0,
+			summariesUpdated: 0,
+			errors: []
+		};
+		const records = await this.storage.getUnaggregatedRecords({
+			metricKey,
+			periodStart,
+			periodEnd,
+			limit: this.batchSize
+		});
+		if (records.length === 0) return result;
+		const groups = this.groupRecords(records, periodType);
+		for (const [groupKey, groupRecords] of groups.entries()) try {
+			await this.aggregateGroup(groupKey, groupRecords, periodType, result);
+		} catch (error) {
+			const [metricKey$1, subjectType, subjectId] = groupKey.split("::");
+			result.errors.push({
+				metricKey: metricKey$1,
+				subjectType,
+				subjectId,
+				error: error instanceof Error ? error.message : String(error)
+			});
+		}
+		const recordIds = records.map((r) => r.id);
+		await this.storage.markRecordsAggregated(recordIds, /* @__PURE__ */ new Date());
+		result.recordsProcessed = records.length;
+		return result;
+	}
+	/**
+	* Group records by metric, subject, and period.
+	*/
+	groupRecords(records, periodType) {
+		const groups = /* @__PURE__ */ new Map();
+		for (const record of records) {
+			const periodKey = formatPeriodKey(record.timestamp, periodType);
+			const groupKey = `${record.metricKey}::${record.subjectType}::${record.subjectId}::${periodKey}`;
+			const existing = groups.get(groupKey) || [];
+			existing.push(record);
+			groups.set(groupKey, existing);
+		}
+		return groups;
+	}
+	/**
+	* Aggregate a group of records into a summary.
+	*/
+	async aggregateGroup(groupKey, records, periodType, result) {
+		const [metricKey, subjectType, subjectId] = groupKey.split("::");
+		if (!metricKey || !subjectType || !subjectId || records.length === 0) return;
+		const firstRecord = records[0];
+		const periodStart = getPeriodStart(firstRecord.timestamp, periodType);
+		const periodEnd = getPeriodEnd(firstRecord.timestamp, periodType);
+		const aggregationType = (await this.storage.getMetric(metricKey))?.aggregationType || "SUM";
+		const quantities = records.map((r) => r.quantity);
+		const aggregated = this.calculateAggregation(quantities, aggregationType);
+		await this.storage.upsertSummary({
+			metricKey,
+			subjectType,
+			subjectId,
+			periodType,
+			periodStart,
+			periodEnd,
+			totalQuantity: aggregated.total,
+			recordCount: records.length,
+			minQuantity: aggregated.min,
+			maxQuantity: aggregated.max,
+			avgQuantity: aggregated.avg
+		});
+		result.summariesCreated++;
+	}
+	/**
+	* Calculate aggregation values.
+	*/
+	calculateAggregation(quantities, aggregationType) {
+		if (quantities.length === 0) return {
+			total: 0,
+			min: 0,
+			max: 0,
+			avg: 0
+		};
+		const min = Math.min(...quantities);
+		const max = Math.max(...quantities);
+		const sum = quantities.reduce((a, b) => a + b, 0);
+		const avg = sum / quantities.length;
+		const count = quantities.length;
+		let total;
+		switch (aggregationType) {
+			case "COUNT":
+				total = count;
+				break;
+			case "SUM":
+				total = sum;
+				break;
+			case "AVG":
+				total = avg;
+				break;
+			case "MAX":
+				total = max;
+				break;
+			case "MIN":
+				total = min;
+				break;
+			case "LAST":
+				total = quantities[quantities.length - 1] ?? 0;
+				break;
+			default: total = sum;
+		}
+		return {
+			total,
+			min,
+			max,
+			avg
+		};
+	}
+};
+/**
+* In-memory usage storage for testing.
+*/
+var InMemoryUsageStorage = class {
+	records = [];
+	summaries = /* @__PURE__ */ new Map();
+	metrics = /* @__PURE__ */ new Map();
+	addRecord(record) {
+		this.records.push(record);
+	}
+	addMetric(metric) {
+		this.metrics.set(metric.key, metric);
+	}
+	async getUnaggregatedRecords(options) {
+		let records = this.records.filter((r) => {
+			const inPeriod = r.timestamp >= options.periodStart && r.timestamp < options.periodEnd;
+			const matchesMetric = !options.metricKey || r.metricKey === options.metricKey;
+			return inPeriod && matchesMetric;
+		});
+		if (options.limit) records = records.slice(0, options.limit);
+		return records;
+	}
+	async markRecordsAggregated(recordIds) {
+		this.records = this.records.filter((r) => !recordIds.includes(r.id));
+	}
+	async upsertSummary(summary) {
+		const key = `${summary.metricKey}::${summary.subjectType}::${summary.subjectId}::${summary.periodType}::${summary.periodStart.toISOString()}`;
+		const existing = this.summaries.get(key);
+		if (existing) {
+			existing.totalQuantity += summary.totalQuantity;
+			existing.recordCount += summary.recordCount;
+			if (summary.minQuantity !== void 0) existing.minQuantity = Math.min(existing.minQuantity ?? Infinity, summary.minQuantity);
+			if (summary.maxQuantity !== void 0) existing.maxQuantity = Math.max(existing.maxQuantity ?? -Infinity, summary.maxQuantity);
+			return existing;
+		}
+		const newSummary = {
+			id: `summary-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+			...summary
+		};
+		this.summaries.set(key, newSummary);
+		return newSummary;
+	}
+	async getMetric(key) {
+		return this.metrics.get(key) || null;
+	}
+	async listMetrics() {
+		return Array.from(this.metrics.values());
+	}
+	getSummaries() {
+		return Array.from(this.summaries.values());
+	}
+	clear() {
+		this.records = [];
+		this.summaries.clear();
+		this.metrics.clear();
+	}
+};
+
+//#endregion
+export { InMemoryUsageStorage, UsageAggregator, formatPeriodKey, getPeriodEnd, getPeriodStart };

package/dist/contracts/dist/capabilities/openbanking.js

@@ -1 +1,88 @@
-import{e}from"../ownership.js";const t=[`platform.finance`],n=[`open-banking`,`finance`];[...t],[...n],e.Experimental,[...t],[...n],e.Experimental,[...t],[...n],e.Experimental;
+import { StabilityEnum } from "../ownership.js";
+
+//#region ../contracts/dist/capabilities/openbanking.js
+const OWNERS = ["platform.finance"];
+const TAGS = ["open-banking", "finance"];
+const openBankingAccountsReadCapability = {
+	meta: {
+		key: "openbanking.accounts.read",
+		version: 1,
+		kind: "integration",
+		title: "Open Banking Accounts (Read)",
+		description: "Provides read-only access to linked bank accounts, including account summaries and metadata.",
+		domain: "finance",
+		owners: [...OWNERS],
+		tags: [...TAGS],
+		stability: StabilityEnum.Experimental
+	},
+	provides: [
+		{
+			surface: "operation",
+			name: "openbanking.accounts.list",
+			version: 1,
+			description: "List bank accounts linked to a Powens open banking connection."
+		},
+		{
+			surface: "operation",
+			name: "openbanking.accounts.get",
+			version: 1,
+			description: "Retrieve the canonical bank account record for a specific account."
+		},
+		{
+			surface: "operation",
+			name: "openbanking.accounts.sync",
+			version: 1,
+			description: "Trigger a refresh of bank account metadata from the open banking provider."
+		}
+	]
+};
+const openBankingTransactionsReadCapability = {
+	meta: {
+		key: "openbanking.transactions.read",
+		version: 1,
+		kind: "integration",
+		title: "Open Banking Transactions (Read)",
+		description: "Enables retrieval of transaction history for linked bank accounts via open banking providers.",
+		domain: "finance",
+		owners: [...OWNERS],
+		tags: [...TAGS, "transactions"],
+		stability: StabilityEnum.Experimental
+	},
+	provides: [{
+		surface: "operation",
+		name: "openbanking.transactions.list",
+		version: 1,
+		description: "List transactions for a given bank account with optional date filtering."
+	}, {
+		surface: "operation",
+		name: "openbanking.transactions.sync",
+		version: 1,
+		description: "Synchronise transactions from the open banking provider into the canonical ledger."
+	}]
+};
+const openBankingBalancesReadCapability = {
+	meta: {
+		key: "openbanking.balances.read",
+		version: 1,
+		kind: "integration",
+		title: "Open Banking Balances (Read)",
+		description: "Allows querying of current and available balances for linked bank accounts via open banking providers.",
+		domain: "finance",
+		owners: [...OWNERS],
+		tags: [...TAGS, "balances"],
+		stability: StabilityEnum.Experimental
+	},
+	provides: [{
+		surface: "operation",
+		name: "openbanking.balances.get",
+		version: 1,
+		description: "Retrieve the latest known balances for a specified bank account."
+	}, {
+		surface: "operation",
+		name: "openbanking.balances.refresh",
+		version: 1,
+		description: "Force a balance refresh from the open banking provider."
+	}]
+};
+
+//#endregion

package/dist/contracts/dist/client/index.js

@@ -1 +1,5 @@
-"use client";import"./react/feature-render.js";import"./react/form-render.js";import"./react/index.js";
+'use client';
+
+import "./react/feature-render.js";
+import "./react/form-render.js";
+import "./react/index.js";

package/dist/contracts/dist/client/react/feature-render.js

@@ -1 +1,2 @@
-import"../../presentations.v2.js";import"react";
+import "../../presentations.v2.js";
+import "react";

package/dist/contracts/dist/client/react/form-render.js

@@ -1 +1,4 @@
-import"react";import"react-hook-form";import"@hookform/resolvers/zod";import"react/jsx-runtime";
+import "react";
+import "react-hook-form";
+import "@hookform/resolvers/zod";
+import "react/jsx-runtime";

package/dist/contracts/dist/client/react/index.js

@@ -1 +1,4 @@
-"use client";import"./feature-render.js";import"./form-render.js";
+'use client';
+
+import "./feature-render.js";
+import "./form-render.js";

package/dist/contracts/dist/contract-registry/index.js

@@ -1 +1 @@
-import{i as e,n as t,r as n}from"./schemas.js";
+import { ContractRegistryFileSchema, ContractRegistryItemSchema, ContractRegistryItemTypeSchema } from "./schemas.js";

package/dist/contracts/dist/contract-registry/schemas.js

@@ -1 +1,60 @@
-import{e}from"../ownership.js";import t from"zod";const n=t.enum([`contractspec:operation`,`contractspec:event`,`contractspec:presentation`,`contractspec:form`,`contractspec:feature`,`contractspec:workflow`,`contractspec:template`,`contractspec:integration`,`contractspec:data-view`,`contractspec:migration`,`contractspec:telemetry`,`contractspec:experiment`,`contractspec:app-config`,`contractspec:knowledge`]),r=t.object({path:t.string().min(1),type:t.string().min(1),content:t.string().optional()}),i=t.object({name:t.string().min(1),type:n,version:t.number().int().nonnegative(),title:t.string().min(1),description:t.string().min(1),meta:t.object({stability:t.enum([e.Idea,e.InCreation,e.Experimental,e.Beta,e.Stable,e.Deprecated]),owners:t.array(t.string().min(1)).default([]),tags:t.array(t.string().min(1)).default([])}),dependencies:t.array(t.string().min(1)).optional(),registryDependencies:t.array(t.string().min(1)).optional(),files:t.array(r).min(1),schema:t.object({input:t.unknown().optional(),output:t.unknown().optional()}).optional()});t.object({$schema:t.string().min(1).optional(),name:t.string().min(1),homepage:t.string().min(1).optional(),items:t.array(i)});export{i,n,r};
+import { StabilityEnum } from "../ownership.js";
+import z from "zod";
+
+//#region ../contracts/dist/contract-registry/schemas.js
+const ContractRegistryItemTypeSchema = z.enum([
+	"contractspec:operation",
+	"contractspec:event",
+	"contractspec:presentation",
+	"contractspec:form",
+	"contractspec:feature",
+	"contractspec:workflow",
+	"contractspec:template",
+	"contractspec:integration",
+	"contractspec:data-view",
+	"contractspec:migration",
+	"contractspec:telemetry",
+	"contractspec:experiment",
+	"contractspec:app-config",
+	"contractspec:knowledge"
+]);
+const ContractRegistryFileSchema = z.object({
+	path: z.string().min(1),
+	type: z.string().min(1),
+	content: z.string().optional()
+});
+const ContractRegistryItemSchema = z.object({
+	name: z.string().min(1),
+	type: ContractRegistryItemTypeSchema,
+	version: z.number().int().nonnegative(),
+	title: z.string().min(1),
+	description: z.string().min(1),
+	meta: z.object({
+		stability: z.enum([
+			StabilityEnum.Idea,
+			StabilityEnum.InCreation,
+			StabilityEnum.Experimental,
+			StabilityEnum.Beta,
+			StabilityEnum.Stable,
+			StabilityEnum.Deprecated
+		]),
+		owners: z.array(z.string().min(1)).default([]),
+		tags: z.array(z.string().min(1)).default([])
+	}),
+	dependencies: z.array(z.string().min(1)).optional(),
+	registryDependencies: z.array(z.string().min(1)).optional(),
+	files: z.array(ContractRegistryFileSchema).min(1),
+	schema: z.object({
+		input: z.unknown().optional(),
+		output: z.unknown().optional()
+	}).optional()
+});
+const ContractRegistryManifestSchema = z.object({
+	$schema: z.string().min(1).optional(),
+	name: z.string().min(1),
+	homepage: z.string().min(1).optional(),
+	items: z.array(ContractRegistryItemSchema)
+});
+
+//#endregion
+export { ContractRegistryFileSchema, ContractRegistryItemSchema, ContractRegistryItemTypeSchema };

package/dist/contracts/dist/docs/PUBLISHING.docblock.js

@@ -1,76 +1,16 @@
-import{a as e}from"./registry.js";e([{id:`docs.PUBLISHING`,title:`Publishing ContractSpec Libraries`,summary:`This guide describes how we release the ContractSpec libraries to npm. We use a dual-track release system: **Stable** (manual) and **Canary** (automatic).`,kind:`reference`,visibility:`public`,route:`/docs/PUBLISHING`,tags:[`PUBLISHING`],body:`# Publishing ContractSpec Libraries
-
-This guide describes how we release the ContractSpec libraries to npm. We use a dual-track release system: **Stable** (manual) and **Canary** (automatic).
-
-## Release Tracks
-
-| Track | Branch | npm Tag | Frequency | Versioning | Use Case |
-|-------|--------|---------|-----------|------------|----------|
-| **Stable** | \`release\` | \`latest\` | Manual | SemVer (e.g., \`1.7.4\`) | Production, external users |
-| **Canary** | \`main\` | \`canary\` | Every Push | Snapshot (e.g., \`1.7.4-canary...\`) | Dev, internal testing |
-
-## Prerequisites
-
-- ✅ \`NPM_TOKEN\` secret is configured in GitHub (owner or automation token with _publish_ scope).
-- ✅ \`GITHUB_TOKEN\` (built-in) has permissions to create PRs (enabled by default in new repos).
-- ✅ For stable releases: \`release\` branch exists and is protected.
-
-## Canary Workflow (Automatic)
-
-Every commit pushed to \`main\` triggers the \`.github/workflows/publish-canary.yml\` workflow.
-
-1. **Trigger**: Push to \`main\`.
-2. **Versioning**: Runs \`changeset version --snapshot canary\` to generate a temporary snapshot version.
-3. **Publish**: Packages are published to npm with the \`canary\` tag using \`changeset publish --tag canary\`.
-
-### Consuming Canary Builds
-
-To install the latest bleeding-edge version:
-
-\`\`\`bash
-npm install @lssm/lib.contracts@canary
-# or
-bun add @lssm/lib.contracts@canary
-\`\`\`
-
-## Stable Release Workflow (Manual)
-
-Stable releases are managed via the \`release\` branch using the standard [Changesets Action](https://github.com/changesets/action).
-
-1. **Develop on \`main\`**: Create features and fixes.
-2. **Add Changesets**: Run \`bun changeset\` to document changes and impact (major/minor/patch).
-3. **Merge to \`release\`**: When ready to ship, open a PR from \`main\` to \`release\` or merge manually.
-4. **"Version Packages" PR**:
-   - The GitHub Action detects new changesets and automatically creates a Pull Request titled **"Version Packages"**.
-   - This PR contains the version bumps and updated \`CHANGELOG.md\` files.
-5. **Merge & Publish**:
-   - Review and merge the "Version Packages" PR.
-   - The Action runs again, detects the versions have been bumped, builds the libraries, and publishes them to npm with the \`latest\` tag.
-
-### Publishing Steps
-
-1. Ensure all changesets are present on \`main\`.
-2. Merge \`main\` into \`release\`:
-   \`\`\`bash
-   git checkout release
-   git pull origin release
-   git merge main
-   git push origin release
-   \`\`\`
-3. Go to GitHub Pull Requests. You will see a **"Version Packages"** PR created by the bot.
-4. Merge that PR.
-5. The release is now live on npm!
-
-## Manual Verification (Optional)
-
-Before publishing a new version you can run:
-
-\`\`\`bash
-bun run build:not-apps
-npx npm-packlist --json packages/libs/contracts
-\`\`\`
-
-## Rollback
-
-If a publish fails mid-way, re-run the workflow once the issue is fixed. Already published packages are skipped automatically. Use \`npm deprecate <package>@<version>\` if we need to warn consumers about a broken release.
-`}]);
+import { registerDocBlocks } from "./registry.js";
+
+//#region ../contracts/dist/docs/PUBLISHING.docblock.js
+const PUBLISHING_DocBlocks = [{
+	id: "docs.PUBLISHING",
+	title: "Publishing ContractSpec Libraries",
+	summary: "This guide describes how we release the ContractSpec libraries to npm. We use a dual-track release system: **Stable** (manual) and **Canary** (automatic).",
+	kind: "reference",
+	visibility: "public",
+	route: "/docs/PUBLISHING",
+	tags: ["PUBLISHING"],
+	body: "# Publishing ContractSpec Libraries\n\nThis guide describes how we release the ContractSpec libraries to npm. We use a dual-track release system: **Stable** (manual) and **Canary** (automatic).\n\n## Release Tracks\n\n| Track | Branch | npm Tag | Frequency | Versioning | Use Case |\n|-------|--------|---------|-----------|------------|----------|\n| **Stable** | `release` | `latest` | Manual | SemVer (e.g., `1.7.4`) | Production, external users |\n| **Canary** | `main` | `canary` | Every Push | Snapshot (e.g., `1.7.4-canary...`) | Dev, internal testing |\n\n## Prerequisites\n\n- ✅ `NPM_TOKEN` secret is configured in GitHub (owner or automation token with _publish_ scope).\n- ✅ `GITHUB_TOKEN` (built-in) has permissions to create PRs (enabled by default in new repos).\n- ✅ For stable releases: `release` branch exists and is protected.\n\n## Canary Workflow (Automatic)\n\nEvery commit pushed to `main` triggers the `.github/workflows/publish-canary.yml` workflow.\n\n1. **Trigger**: Push to `main`.\n2. **Versioning**: Runs `changeset version --snapshot canary` to generate a temporary snapshot version.\n3. **Publish**: Packages are published to npm with the `canary` tag using `changeset publish --tag canary`.\n\n### Consuming Canary Builds\n\nTo install the latest bleeding-edge version:\n\n```bash\nnpm install @lssm/lib.contracts@canary\n# or\nbun add @lssm/lib.contracts@canary\n```\n\n## Stable Release Workflow (Manual)\n\nStable releases are managed via the `release` branch using the standard [Changesets Action](https://github.com/changesets/action).\n\n1. **Develop on `main`**: Create features and fixes.\n2. **Add Changesets**: Run `bun changeset` to document changes and impact (major/minor/patch).\n3. **Merge to `release`**: When ready to ship, open a PR from `main` to `release` or merge manually.\n4. **\"Version Packages\" PR**:\n   - The GitHub Action detects new changesets and automatically creates a Pull Request titled **\"Version Packages\"**.\n   - This PR contains the version bumps and updated `CHANGELOG.md` files.\n5. **Merge & Publish**:\n   - Review and merge the \"Version Packages\" PR.\n   - The Action runs again, detects the versions have been bumped, builds the libraries, and publishes them to npm with the `latest` tag.\n\n### Publishing Steps\n\n1. Ensure all changesets are present on `main`.\n2. Merge `main` into `release`:\n   ```bash\n   git checkout release\n   git pull origin release\n   git merge main\n   git push origin release\n   ```\n3. Go to GitHub Pull Requests. You will see a **\"Version Packages\"** PR created by the bot.\n4. Merge that PR.\n5. The release is now live on npm!\n\n## Manual Verification (Optional)\n\nBefore publishing a new version you can run:\n\n```bash\nbun run build:not-apps\nnpx npm-packlist --json packages/libs/contracts\n```\n\n## Rollback\n\nIf a publish fails mid-way, re-run the workflow once the issue is fixed. Already published packages are skipped automatically. Use `npm deprecate <package>@<version>` if we need to warn consumers about a broken release.\n"
+}];
+registerDocBlocks(PUBLISHING_DocBlocks);
+
+//#endregion