@warpgogol/werkstatt-shared 0.2.0

package/src/observability/tests/redact.pbt.test.ts

@@ -0,0 +1,71 @@
+/*
+<MODULE_CONTRACT>
+  <purpose>RFC-0347: property-based tests for redactUrl safety invariants.</purpose>
+  <keywords>RFC-0347, PBT, fast-check, redact, url, observability</keywords>
+  <responsibilities>
+    <item>Verify redactUrl never contains a query string in output.</item>
+    <item>Verify redactUrl never contains a fragment in output.</item>
+    <item>Verify redactUrl is idempotent.</item>
+    <item>Verify redactUrl host is always lowercase.</item>
+  </responsibilities>
+</MODULE_CONTRACT>
+<MODULE_MAP><entry key="pbt-redact-url">Property-based tests for redactUrl safety invariants.</entry></MODULE_MAP>
+<CHANGE_SUMMARY><item>RFC-0347: initial PBT illustrative example for redactUrl invariants.</item></CHANGE_SUMMARY>
+*/
+
+import { test, expect } from "vitest";
+import fc from "fast-check";
+import { redactUrl } from "../redact.ts";
+
+const urlArbitrary = fc.webUrl();
+
+test("PBT: redactUrl output never contains a query string", () => {
+  fc.assert(
+    fc.property(urlArbitrary, (url) => {
+      const redacted = redactUrl(url);
+      try {
+        const parsed = new URL(redacted);
+        expect(parsed.search).toBe("");
+      } catch {
+        // non-URL input passes through unchanged — skip
+      }
+    }),
+  );
+});
+
+test("PBT: redactUrl output never contains a fragment", () => {
+  fc.assert(
+    fc.property(urlArbitrary, (url) => {
+      const redacted = redactUrl(url);
+      try {
+        const parsed = new URL(redacted);
+        expect(parsed.hash).toBe("");
+      } catch {
+        // non-URL input passes through unchanged — skip
+      }
+    }),
+  );
+});
+
+test("PBT: redactUrl is idempotent — redact(redact(url)) === redact(url)", () => {
+  fc.assert(
+    fc.property(urlArbitrary, (url) => {
+      const once = redactUrl(url);
+      expect(redactUrl(once)).toBe(once);
+    }),
+  );
+});
+
+test("PBT: redactUrl host is always lowercase", () => {
+  fc.assert(
+    fc.property(urlArbitrary, (url) => {
+      const redacted = redactUrl(url);
+      try {
+        const parsed = new URL(redacted);
+        expect(parsed.hostname).toBe(parsed.hostname.toLowerCase());
+      } catch {
+        // non-URL input passes through unchanged — skip
+      }
+    }),
+  );
+});

package/src/observability/tests/redact.test.ts

@@ -0,0 +1,37 @@
+import { describe, it, expect } from "vitest";
+import { redactUrl } from "../redact.ts";
+
+describe("redactUrl", () => {
+  it("strips query string and fragment", () => {
+    expect(redactUrl("https://a.b/p?q=1#f")).toBe("https://a.b/p");
+  });
+
+  it("strips only query string when no fragment", () => {
+    expect(redactUrl("https://a.b/p?q=1")).toBe("https://a.b/p");
+  });
+
+  it("strips only fragment when no query string", () => {
+    expect(redactUrl("https://a.b/p#section")).toBe("https://a.b/p");
+  });
+
+  it("lowercases the host", () => {
+    expect(redactUrl("https://EXAMPLE.COM/Path")).toBe("https://example.com/Path");
+  });
+
+  it("preserves path case", () => {
+    expect(redactUrl("https://a.b/CaseSensitive/Path?q=1")).toBe("https://a.b/CaseSensitive/Path");
+  });
+
+  it("returns input unchanged for invalid URLs", () => {
+    expect(redactUrl("not a url")).toBe("not a url");
+  });
+
+  it("handles root path", () => {
+    expect(redactUrl("https://a.b/?q=1#f")).toBe("https://a.b");
+  });
+
+  it("preserves non-root path slashes so repeated redaction is stable", () => {
+    expect(redactUrl("http://a.aa//")).toBe("http://a.aa//");
+    expect(redactUrl(redactUrl("http://a.aa//"))).toBe("http://a.aa//");
+  });
+});

package/src/observability/typed-refs.ts

@@ -0,0 +1,137 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Maintains packages/observability/src/typed-refs.ts as an authored observability authored module so agents can evolve it without rediscovering local boundaries.</purpose>
+<non-goals>
+  <item>Do not import node: modules — must be Workers-compatible.</item>
+  <item>Do not define metric specs (kind, help, unit, buckets) — metric-registry.ts is the runtime authority.</item>
+</non-goals>
+@ai-invariant: METRIC_REFS keys must match WARPGOGOL_METRIC_REGISTRY names exactly — enforced by compile-time type assertion below.
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Add typed metric references for compile-time label-key enforcement across all consumers.</item>
+  <item>wg-review: correct non-goals, add compile-time registry-coverage assertion.</item>
+  <item>RFC-0807: add back prefix metric refs for service health monitoring.</item>
+</CHANGE_SUMMARY>
+*/
+
+import type { MetricsPusher } from "./pusher.ts";
+import { WARPGOGOL_METRIC_REGISTRY } from "./metric-registry.ts";
+
+type LabelKeys<L extends readonly string[]> = L[number];
+type LabelMap<L extends readonly string[]> = Partial<Record<LabelKeys<L>, string>>;
+
+export interface TypedCounter<L extends readonly string[]> {
+  readonly name: string;
+  add(pusher: MetricsPusher, value: number, labels?: LabelMap<L>): void;
+}
+
+export interface TypedGauge<L extends readonly string[]> {
+  readonly name: string;
+  set(pusher: MetricsPusher, value: number, labels?: LabelMap<L>): void;
+}
+
+export interface TypedHistogram<L extends readonly string[]> {
+  readonly name: string;
+  record(pusher: MetricsPusher, value: number, labels?: LabelMap<L>): void;
+}
+
+function defineCounter<L extends readonly string[]>(name: string, _labelKeys: L): TypedCounter<L> {
+  return {
+    name,
+    add(pusher, value, labels) {
+      pusher.counterAdd(name, value, (labels ?? {}) as Record<string, string>);
+    },
+  };
+}
+
+function defineGauge<L extends readonly string[]>(name: string, _labelKeys: L): TypedGauge<L> {
+  return {
+    name,
+    set(pusher, value, labels) {
+      pusher.gaugeSet(name, value, (labels ?? {}) as Record<string, string>);
+    },
+  };
+}
+
+function defineHistogram<L extends readonly string[]>(
+  name: string,
+  _labelKeys: L,
+): TypedHistogram<L> {
+  return {
+    name,
+    record(pusher, value, labels) {
+      pusher.histogramRecord(name, value, (labels ?? {}) as Record<string, string>);
+    },
+  };
+}
+
+export const METRIC_REFS = {
+  warpgogol_factory_smoke_total: defineCounter("warpgogol_factory_smoke_total", [] as const),
+  warpgogol_factory_command_runs_total: defineCounter("warpgogol_factory_command_runs_total", [
+    "command",
+    "status",
+    "site_id",
+  ] as const),
+  warpgogol_factory_command_duration_seconds: defineHistogram(
+    "warpgogol_factory_command_duration_seconds",
+    ["command", "site_id"] as const,
+  ),
+  warpgogol_factory_diagnostics_total: defineCounter("warpgogol_factory_diagnostics_total", [
+    "command",
+    "severity",
+    "site_id",
+  ] as const),
+  warpgogol_probe_up: defineGauge("warpgogol_probe_up", ["site_id", "route"] as const),
+  warpgogol_probe_ttfb_seconds: defineGauge("warpgogol_probe_ttfb_seconds", [
+    "site_id",
+    "route",
+  ] as const),
+  warpgogol_probe_http_status_class_total: defineCounter(
+    "warpgogol_probe_http_status_class_total",
+    ["site_id", "route", "status_class"] as const,
+  ),
+  warpgogol_probe_content_ok: defineGauge("warpgogol_probe_content_ok", [
+    "site_id",
+    "route",
+  ] as const),
+  warpgogol_probe_cert_expiry_days: defineGauge("warpgogol_probe_cert_expiry_days", [
+    "site_id",
+  ] as const),
+  warpgogol_probe_deep_ok: defineGauge("warpgogol_probe_deep_ok", ["site_id"] as const),
+  warpgogol_delivery_requests_total: defineCounter("warpgogol_delivery_requests_total", [
+    "site_id",
+    "cache_status",
+    "status_class",
+  ] as const),
+  warpgogol_delivery_bytes_total: defineCounter("warpgogol_delivery_bytes_total", [
+    "site_id",
+  ] as const),
+  warpgogol_workers_requests_total: defineCounter("warpgogol_workers_requests_total", [
+    "site_id",
+  ] as const),
+  warpgogol_workers_errors_total: defineCounter("warpgogol_workers_errors_total", [
+    "site_id",
+  ] as const),
+  warpgogol_back_requests_total: defineCounter("warpgogol_back_requests_total", [
+    "service",
+    "status_class",
+  ] as const),
+  warpgogol_back_up: defineGauge("warpgogol_back_up", ["service"] as const),
+  warpgogol_back_last_run_total: defineCounter("warpgogol_back_last_run_total", [
+    "service",
+    "status",
+  ] as const),
+  warpgogol_back_last_error_total: defineCounter("warpgogol_back_last_error_total", [
+    "service",
+  ] as const),
+  warpgogol_back_queue_depth: defineGauge("warpgogol_back_queue_depth", ["service"] as const),
+} as const;
+
+// Compile-time assertion: every METRIC_REFS key must be a declared registry metric name.
+// If a metric is added to METRIC_REFS but not to WARPGOGOL_METRIC_REGISTRY (or vice versa),
+// this type expression produces a compile error.
+type _RegistryNames = (typeof WARPGOGOL_METRIC_REGISTRY)[number]["name"];
+type _RefKeys = keyof typeof METRIC_REFS;
+type _DriftCheck = _RefKeys extends _RegistryNames ? true : never;
+const _assertNoDrift: _DriftCheck = true;
+void _assertNoDrift;

package/src/observability/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    environment: "node",
+    include: ["src/**/*.test.ts"],
+  },
+});

package/src/ontology/analytics/matomo-binding.yaml

@@ -0,0 +1,172 @@
+kind: analytics-matomo-binding
+id: warpgogol-matomo-binding
+version: 1.0.0
+rfc: RFC-0305
+messkanonVersion: 1.0.0
+
+meta:
+  title: Warpgogol Matomo Binding
+  description: Replaceable mapping from Warpgogol Messkanon v1 to Matomo Cloud/On-Premise entities.
+  status: active
+  changelog:
+    - version: 1.0.0
+      date: 2026-07-06
+      summary: Initial RFC-0305 Matomo event, goal, dimension, provisioning, and export mapping.
+
+tracker:
+  proxyPath: /_wg/analytics/
+  scriptPath: matomo.js
+  endpointPath: matomo.php
+  privacyProfile: bannerfrei-v1
+  requestMethod: POST
+  requiredQueueCalls:
+    - disableCookies
+    - disableBrowserFeatureDetection
+    - setDoNotTrack
+    - setTrackerUrl
+    - setSiteId
+    - trackPageView
+    - enableLinkTracking
+  forbiddenQueueCalls:
+    - rememberConsentGiven
+    - rememberCookieConsentGiven
+    - enableHeartBeatTimer
+    - setUserId
+    - enableCrossDomainLinking
+
+events:
+  - semanticId: contact.phone_click
+    matomo:
+      category: contact
+      action: phone_click
+      nameFrom: payload.placement
+  - semanticId: contact.form_submit
+    matomo:
+      category: contact
+      action: form_submit
+      nameFrom: payload.formId
+  - semanticId: contact.whatsapp_click
+    matomo:
+      category: contact
+      action: whatsapp_click
+      nameFrom: payload.placement
+  - semanticId: contact.email_click
+    matomo:
+      category: contact
+      action: email_click
+      nameFrom: payload.placement
+  - semanticId: contact.route_click
+    matomo:
+      category: contact
+      action: route_click
+      nameFrom: payload.placement
+
+goals:
+  - key: anfrage_telefon
+    name: Anfrage Telefon
+    semanticId: contact.phone_click
+    match:
+      type: event
+      category: contact
+      action: phone_click
+  - key: anfrage_formular
+    name: Anfrage Formular
+    semanticId: contact.form_submit
+    match:
+      type: event
+      category: contact
+      action: form_submit
+  - key: anfrage_whatsapp
+    name: Anfrage WhatsApp
+    semanticId: contact.whatsapp_click
+    match:
+      type: event
+      category: contact
+      action: whatsapp_click
+  - key: anfrage_email
+    name: Anfrage E-Mail
+    semanticId: contact.email_click
+    match:
+      type: event
+      category: contact
+      action: email_click
+
+dimensions:
+  visit:
+    - name: client_id
+      required: true
+      idSource: fleet.registry
+    - name: messkanon_version
+      required: true
+      idSource: fleet.registry
+    - name: consent_level
+      required: true
+      idSource: fleet.registry
+  action:
+    - name: site_type
+      required: true
+      idSource: fleet.registry
+    - name: page_type
+      required: true
+      idSource: fleet.registry
+    - name: surface_module
+      required: false
+      idSource: fleet.registry
+    - name: pseo_industry
+      required: false
+      idSource: fleet.registry
+    - name: pseo_city
+      required: false
+      idSource: fleet.registry
+    - name: pseo_demand
+      required: false
+      idSource: fleet.registry
+    - name: pseo_locale
+      required: false
+      idSource: fleet.registry
+    - name: pseo_arm
+      required: false
+      idSource: fleet.registry
+    - name: pseo_experiment
+      required: false
+      idSource: fleet.registry
+    - name: pseo_substance_band
+      required: false
+      idSource: fleet.registry
+    - name: pseo_link_model
+      required: false
+      idSource: fleet.registry
+
+siteDefaults:
+  timezone: Europe/Berlin
+  currency: EUR
+  excludeUnknownUrls: true
+  rawRetentionMonths: 24
+  reportRetention: forever
+  heatmapsEnabled: false
+  sessionRecordingsEnabled: false
+
+provisioning:
+  apiMethods:
+    - SitesManager.addSite
+    - Goals.addGoal
+    - CustomDimensions.configureNewCustomDimension
+  idempotencyKey: clientSemanticId
+  registryRequired: true
+
+smoke:
+  syntheticEvent: contact.route_click
+  syntheticName: anfahrt
+  expectFirstSignal: true
+
+exportPackage:
+  includes:
+    - aggregateReports
+    - rawVisitsWithinRetention
+    - siteConfiguration
+    - goals
+    - dimensions
+    - messkanonVersion
+    - matomoBindingVersion
+    - readme
+    - manifestHashes

package/src/ontology/analytics/matomo-fleet.registry.yaml

@@ -0,0 +1,26 @@
+kind: analytics-matomo-fleet-registry
+schemaVersion: 1
+version: 1.0.0
+updatedAt: 2026-08-08
+owner: architecture
+policy:
+  sourceOfTruth: git
+  manualMatomoUiChanges: forbidden
+  productionAdapterRequiresRecord: true
+  siteIdSource: provisioning
+  noSecrets: true
+sites:
+  - appId: warpgogol-com
+    clientSemanticId: warpgogol-com
+    siteId: "1"
+    matomoCloudHost: warpgogol.matomo.cloud
+    status: active
+    provisionedAt: "2026-08-08"
+    dimensions:
+      visit:
+        client_id: 1
+        messkanon_version: 2
+        consent_level: 3
+      action:
+        site_type: 4
+        page_type: 5

package/src/ontology/analytics/messkanon.yaml

@@ -0,0 +1,151 @@
+kind: analytics-messkanon
+id: warpgogol-messkanon
+version: 1.0.0
+rfc: RFC-0305
+
+meta:
+  title: Warpgogol Messkanon
+  description: Tool-independent analytics vocabulary for thin Warpgogol sites.
+  status: active
+  changelog:
+    - version: 1.0.0
+      date: 2026-07-06
+      summary: Initial RFC-0305 contact-outcome vocabulary.
+
+principles:
+  measureOutcomesNotBehavior: true
+  noPii: true
+  noBehavioralSessionReplay: true
+  defaultConsentLevel: bannerfrei
+
+events:
+  - semanticId: contact.phone_click
+    category: contact
+    action: phone_click
+    nameValues: [header, footer, sticky, contact_page]
+    goalEligible: true
+    goalKey: anfrage_telefon
+    payload:
+      required: [placement]
+      properties:
+        placement:
+          type: enum
+          values: [header, footer, sticky, contact_page]
+  - semanticId: contact.form_submit
+    category: contact
+    action: form_submit
+    nameValues: [kontaktformular, send_message, lead_form]
+    goalEligible: true
+    goalKey: anfrage_formular
+    payload:
+      required: [formId]
+      properties:
+        formId:
+          type: string
+  - semanticId: contact.whatsapp_click
+    category: contact
+    action: whatsapp_click
+    nameValues: [sticky, footer, contact_page]
+    goalEligible: true
+    goalKey: anfrage_whatsapp
+    payload:
+      required: [placement]
+      properties:
+        placement:
+          type: enum
+          values: [sticky, footer, contact_page]
+  - semanticId: contact.email_click
+    category: contact
+    action: email_click
+    nameValues: [footer, impressum, contact_page]
+    goalEligible: true
+    goalKey: anfrage_email
+    payload:
+      required: [placement]
+      properties:
+        placement:
+          type: enum
+          values: [footer, impressum, contact_page]
+  - semanticId: contact.route_click
+    category: contact
+    action: route_click
+    nameValues: [anfahrt, map, footer]
+    goalEligible: false
+    payload:
+      required: [placement]
+      properties:
+        placement:
+          type: enum
+          values: [anfahrt, map, footer]
+
+kpis:
+  - id: visits_30d
+    source: matomo.report
+    report: VisitsSummary.get
+    period: last_30_days
+  - id: anfragen_30d
+    source: messkanon.goals
+    goals: [anfrage_telefon, anfrage_formular, anfrage_whatsapp, anfrage_email]
+    period: last_30_days
+  - id: top_source_30d
+    source: matomo.report
+    report: Referrers.getAll
+    period: last_30_days
+  - id: anfrage_by_channel_30d
+    source: messkanon.goals
+    goals: [anfrage_telefon, anfrage_formular, anfrage_whatsapp, anfrage_email]
+    period: last_30_days
+  - id: kontaktbilanz_quarter
+    source: messkanon.goals
+    goals: [anfrage_telefon, anfrage_formular, anfrage_whatsapp, anfrage_email]
+    period: quarter
+
+campaignParameters:
+  allowed: [utm_source, utm_medium, utm_campaign, utm_content, utm_term]
+  forbidPii: true
+
+dimensions:
+  visit:
+    - name: client_id
+      required: true
+      valueSource: fleet.clientSemanticId
+    - name: messkanon_version
+      required: true
+      valueSource: ontology.analytics.messkanon.version
+    - name: consent_level
+      required: true
+      valueSource: constant.bannerfrei
+  action:
+    - name: site_type
+      required: true
+      valueSource: system.growth.vendor.options.siteType
+    - name: page_type
+      required: true
+      valueSource: page.context.pageType
+    - name: surface_module
+      required: false
+      valueSource: page.context.surfaceModule
+    - name: pseo_industry
+      required: false
+      valueSource: page.context.pseo.industry
+    - name: pseo_city
+      required: false
+      valueSource: page.context.pseo.city
+    - name: pseo_demand
+      required: false
+      valueSource: page.context.pseo.demand
+    - name: pseo_locale
+      required: false
+      valueSource: page.context.pseo.locale
+    - name: pseo_arm
+      required: false
+      valueSource: page.context.pseo.arm
+    - name: pseo_experiment
+      required: false
+      valueSource: page.context.pseo.experiment
+    - name: pseo_substance_band
+      required: false
+      valueSource: page.context.pseo.substanceBand
+    - name: pseo_link_model
+      required: false
+      valueSource: page.context.pseo.linkModel

package/src/ontology/archetype-registry.ts

@@ -0,0 +1,61 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+Re-export the derived planetImportPaths, blockTypeToCosmicName, moonImportPaths,
+and roleByCosmicName maps from the canonical archetype registry index.json
+(RFC-0091). Validates the JSON shape at import time so registry drift fails
+fast instead of producing silently empty maps.
+</purpose>
+<non-goals>
+  <item>Do not own the build logic that produces index.json.</item>
+  <item>Do not re-derive or transform the maps.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0091: Initial creation — typed re-export of derived archetype registry maps.</item>
+  <item>RFC-0263: also re-export roleByCosmicName (manifest-authored role, derived) — replaces name-keyed dispatch literals in packages/share.</item>
+  <item>Architecture review 2026-07-10: validate index.json with Zod instead of unchecked cast — fail-fast on registry shape drift.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { z } from "zod";
+import indexJson from "./archetypes/index.json";
+
+const recordStringString = z.record(z.string(), z.string());
+
+const archetypeRegistryIndexSchema = z.object({
+  schemaVersion: z.string().min(1),
+  totalCount: z.number().int().nonnegative(),
+  entries: z.array(
+    z.object({
+      id: z.string().min(1),
+      displayName: z.string().min(1),
+      semanticRole: z.string().min(1),
+      version: z.string().min(1),
+      layoutHint: z.string().min(1),
+      acceptedCosmicNames: z.array(z.string().min(1)),
+      sourceFile: z.string().min(1),
+      layer: z.enum(["section", "component"]),
+    }),
+  ),
+  sectionRoles: z.array(z.string().min(1)),
+  componentRoles: z.array(z.string().min(1)),
+  planetImportPaths: recordStringString,
+  blockTypeToCosmicName: recordStringString,
+  moonImportPaths: recordStringString.optional().default({}),
+  roleByCosmicName: recordStringString.optional().default({}),
+});
+
+const _parsed = archetypeRegistryIndexSchema.safeParse(indexJson);
+if (!_parsed.success) {
+  const issues = _parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ");
+  throw new Error(
+    `archetype-registry: archetypes/index.yaml failed validation — ${issues}. Regenerate with the archetype registry build command.`,
+  );
+}
+const registry = _parsed.data;
+
+export const planetImportPaths: Record<string, string> = registry.planetImportPaths;
+export const blockTypeToCosmicName: Record<string, string> = registry.blockTypeToCosmicName;
+export const moonImportPaths: Record<string, string> = registry.moonImportPaths;
+export const roleByCosmicName: Record<string, string> = registry.roleByCosmicName;

package/src/ontology/archetypes/components/brand-label.yaml

@@ -0,0 +1,19 @@
+id: brand-label
+displayName: Brand Label
+version: 1.0.0
+semanticRole: component-brand-label
+description: |
+  Starter RFC-0072 archetype seeded from existing manifest metadata.
+expectedIntents:
+  - establish-identity
+  - guide-navigation
+expectedIndustryFit:
+  - non-profit
+layoutHint: split
+propsSchema:
+  $shape: zod
+  shape: |
+    z.object({}).passthrough()
+acceptedCosmicNames:
+  - Proteus
+constraints: {}