@principal-ai/subsystems-core 0.29.0

package/dist/spans/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Spans module
+ *
+ * Provides utilities for working with span conventions from .spans.canvas files.
+ * Span colors are used as fill colors for events emitted within that span.
+ *
+ * Color Contract:
+ * - Scope color → Border (from library.yaml owned-scopes)
+ * - Span color → Fill (from .spans.canvas)
+ */
+export { DEFAULT_SPAN_COLOR, extractSpanConvention, extractSpanConventions, buildSpanColorMap, buildSpanColorMapFromCanvases, buildSpanIconMap, matchSpanPattern, getSpanColor, getSpanIcon, resolveEventSpanColor, type NormalizedSpanConvention, } from './utils';
+//# sourceMappingURL=index.d.ts.map

package/dist/spans/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/spans/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EACL,kBAAkB,EAClB,qBAAqB,EACrB,sBAAsB,EACtB,iBAAiB,EACjB,6BAA6B,EAC7B,gBAAgB,EAChB,gBAAgB,EAChB,YAAY,EACZ,WAAW,EACX,qBAAqB,EACrB,KAAK,wBAAwB,GAC9B,MAAM,SAAS,CAAC"}

package/dist/spans/index.js

@@ -0,0 +1,25 @@
+"use strict";
+/**
+ * Spans module
+ *
+ * Provides utilities for working with span conventions from .spans.canvas files.
+ * Span colors are used as fill colors for events emitted within that span.
+ *
+ * Color Contract:
+ * - Scope color → Border (from library.yaml owned-scopes)
+ * - Span color → Fill (from .spans.canvas)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveEventSpanColor = exports.getSpanIcon = exports.getSpanColor = exports.matchSpanPattern = exports.buildSpanIconMap = exports.buildSpanColorMapFromCanvases = exports.buildSpanColorMap = exports.extractSpanConventions = exports.extractSpanConvention = exports.DEFAULT_SPAN_COLOR = void 0;
+var utils_1 = require("./utils");
+Object.defineProperty(exports, "DEFAULT_SPAN_COLOR", { enumerable: true, get: function () { return utils_1.DEFAULT_SPAN_COLOR; } });
+Object.defineProperty(exports, "extractSpanConvention", { enumerable: true, get: function () { return utils_1.extractSpanConvention; } });
+Object.defineProperty(exports, "extractSpanConventions", { enumerable: true, get: function () { return utils_1.extractSpanConventions; } });
+Object.defineProperty(exports, "buildSpanColorMap", { enumerable: true, get: function () { return utils_1.buildSpanColorMap; } });
+Object.defineProperty(exports, "buildSpanColorMapFromCanvases", { enumerable: true, get: function () { return utils_1.buildSpanColorMapFromCanvases; } });
+Object.defineProperty(exports, "buildSpanIconMap", { enumerable: true, get: function () { return utils_1.buildSpanIconMap; } });
+Object.defineProperty(exports, "matchSpanPattern", { enumerable: true, get: function () { return utils_1.matchSpanPattern; } });
+Object.defineProperty(exports, "getSpanColor", { enumerable: true, get: function () { return utils_1.getSpanColor; } });
+Object.defineProperty(exports, "getSpanIcon", { enumerable: true, get: function () { return utils_1.getSpanIcon; } });
+Object.defineProperty(exports, "resolveEventSpanColor", { enumerable: true, get: function () { return utils_1.resolveEventSpanColor; } });
+//# sourceMappingURL=index.js.map

package/dist/spans/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/spans/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;;;AAEH,iCAYiB;AAXf,2GAAA,kBAAkB,OAAA;AAClB,8GAAA,qBAAqB,OAAA;AACrB,+GAAA,sBAAsB,OAAA;AACtB,0GAAA,iBAAiB,OAAA;AACjB,sHAAA,6BAA6B,OAAA;AAC7B,yGAAA,gBAAgB,OAAA;AAChB,yGAAA,gBAAgB,OAAA;AAChB,qGAAA,YAAY,OAAA;AACZ,oGAAA,WAAW,OAAA;AACX,8GAAA,qBAAqB,OAAA"}

package/dist/spans/utils.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Span utility functions
+ *
+ * Helpers for working with span conventions from .spans.canvas files.
+ * Span colors are used as fill colors for events emitted within that span.
+ */
+import type { ExtendedCanvas, ExtendedCanvasNode } from '../types/canvas';
+/** Default color for spans without a defined color */
+export declare const DEFAULT_SPAN_COLOR = "#9CA3AF";
+/**
+ * Normalized span convention entry
+ */
+export interface NormalizedSpanConvention {
+    /** Unique identifier for this span convention */
+    id: string;
+    /** Pattern to match span names (e.g., "validate.*") */
+    spanPattern: string;
+    /** Color for this span (used as fill for events) */
+    color: string;
+    /** Icon identifier (Lucide icons) */
+    icon?: string;
+    /** Human-readable description */
+    description?: string;
+    /** Status of the span convention */
+    status?: 'draft' | 'approved' | 'implemented';
+}
+/**
+ * Extract span convention from a canvas node
+ */
+export declare function extractSpanConvention(node: ExtendedCanvasNode): NormalizedSpanConvention | null;
+/**
+ * Extract all span conventions from a spans.canvas file
+ */
+export declare function extractSpanConventions(canvas: ExtendedCanvas): NormalizedSpanConvention[];
+/**
+ * Build a span color map from a spans.canvas
+ * Returns a map of spanPattern -> color for fast lookups
+ */
+export declare function buildSpanColorMap(canvas: ExtendedCanvas | null | undefined): Record<string, string>;
+/**
+ * Build a span color map from multiple spans.canvas files
+ * Later files override earlier ones for duplicate patterns
+ */
+export declare function buildSpanColorMapFromCanvases(canvases: (ExtendedCanvas | null | undefined)[]): Record<string, string>;
+/**
+ * Match a span name to a span pattern
+ * Supports exact matches and wildcard patterns (e.g., "validate.*")
+ */
+export declare function matchSpanPattern(spanName: string, pattern: string): boolean;
+/**
+ * Find the color for a span name by matching against span patterns
+ * Returns the first matching pattern's color, or default if none match
+ */
+export declare function getSpanColor(spanName: string, spanColorMap: Record<string, string>): string;
+/**
+ * Resolve span color for an event based on its workflow's spanPattern
+ * This is the primary method for determining event fill color
+ */
+export declare function resolveEventSpanColor(workflowSpanPattern: string | undefined, spanColorMap: Record<string, string>): string;
+/**
+ * Build a span icon map from a spans.canvas
+ * Returns a map of spanPattern -> icon for fast lookups
+ */
+export declare function buildSpanIconMap(canvas: ExtendedCanvas | null | undefined): Record<string, string>;
+/**
+ * Find the icon for a span name by matching against span patterns
+ * Returns the first matching pattern's icon, or undefined if none match
+ */
+export declare function getSpanIcon(spanName: string, spanIconMap: Record<string, string>): string | undefined;
+//# sourceMappingURL=utils.d.ts.map

package/dist/spans/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/spans/utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAG1E,sDAAsD;AACtD,eAAO,MAAM,kBAAkB,YAAY,CAAC;AAE5C;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,iDAAiD;IACjD,EAAE,EAAE,MAAM,CAAC;IACX,uDAAuD;IACvD,WAAW,EAAE,MAAM,CAAC;IACpB,oDAAoD;IACpD,KAAK,EAAE,MAAM,CAAC;IACd,qCAAqC;IACrC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iCAAiC;IACjC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oCAAoC;IACpC,MAAM,CAAC,EAAE,OAAO,GAAG,UAAU,GAAG,aAAa,CAAC;CAC/C;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,kBAAkB,GAAG,wBAAwB,GAAG,IAAI,CA2D/F;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,cAAc,GAAG,wBAAwB,EAAE,CAazF;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAWnG;AAED;;;GAGG;AACH,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,CAAC,cAAc,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,GAC9C,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAYxB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAW3E;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACnC,MAAM,CAcR;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,mBAAmB,EAAE,MAAM,GAAG,SAAS,EACvC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACnC,MAAM,CASR;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAalG;AAED;;;GAGG;AACH,wBAAgB,WAAW,CACzB,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAClC,MAAM,GAAG,SAAS,CAcpB"}

package/dist/spans/utils.js

@@ -0,0 +1,205 @@
+"use strict";
+/**
+ * Span utility functions
+ *
+ * Helpers for working with span conventions from .spans.canvas files.
+ * Span colors are used as fill colors for events emitted within that span.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getSpanIcon = exports.buildSpanIconMap = exports.resolveEventSpanColor = exports.getSpanColor = exports.matchSpanPattern = exports.buildSpanColorMapFromCanvases = exports.buildSpanColorMap = exports.extractSpanConventions = exports.extractSpanConvention = exports.DEFAULT_SPAN_COLOR = void 0;
+const canvas_1 = require("../types/canvas");
+/** Default color for spans without a defined color */
+exports.DEFAULT_SPAN_COLOR = '#9CA3AF'; // gray-400
+/**
+ * Extract span convention from a canvas node
+ */
+function extractSpanConvention(node) {
+    // Handle OTEL span convention nodes (top-level otel field)
+    if ((0, canvas_1.isOtelSpanConventionNode)(node)) {
+        const spanPattern = node.otel?.spanPattern;
+        if (!spanPattern)
+            return null;
+        const color = node.color;
+        if (!color)
+            return null;
+        return {
+            id: node.id,
+            spanPattern,
+            color,
+            icon: node.icon,
+            description: node.description,
+            status: node.otel?.status,
+        };
+    }
+    // Handle standard nodes with pv.nodeType === 'span-convention'
+    if (!(0, canvas_1.isStandardCanvasNode)(node))
+        return null;
+    const pv = node.pv;
+    if (!pv)
+        return null;
+    const nodeType = pv.nodeType;
+    if (nodeType !== 'span-convention')
+        return null;
+    const otel = pv.otel;
+    const spanPattern = otel?.spanPattern;
+    if (!spanPattern)
+        return null;
+    // Get color from node (required for span conventions)
+    const color = node.color;
+    if (!color)
+        return null;
+    // Extract description from node text if present (only text nodes have text)
+    let description;
+    if ('text' in node && typeof node.text === 'string') {
+        const text = node.text;
+        // Try to extract description from markdown (lines after the header)
+        const lines = text.split('\n');
+        const descLines = lines.filter(line => !line.startsWith('#') && line.trim());
+        if (descLines.length > 0) {
+            description = descLines.join(' ').trim();
+        }
+    }
+    // Get icon from pv.icon (Lucide icon identifier)
+    const icon = pv.icon;
+    return {
+        id: node.id,
+        spanPattern,
+        color,
+        icon,
+        description,
+        status: pv.status,
+    };
+}
+exports.extractSpanConvention = extractSpanConvention;
+/**
+ * Extract all span conventions from a spans.canvas file
+ */
+function extractSpanConventions(canvas) {
+    const conventions = [];
+    if (!canvas.nodes)
+        return conventions;
+    for (const node of canvas.nodes) {
+        const convention = extractSpanConvention(node);
+        if (convention) {
+            conventions.push(convention);
+        }
+    }
+    return conventions;
+}
+exports.extractSpanConventions = extractSpanConventions;
+/**
+ * Build a span color map from a spans.canvas
+ * Returns a map of spanPattern -> color for fast lookups
+ */
+function buildSpanColorMap(canvas) {
+    const colorMap = {};
+    if (!canvas)
+        return colorMap;
+    const conventions = extractSpanConventions(canvas);
+    for (const convention of conventions) {
+        colorMap[convention.spanPattern] = convention.color;
+    }
+    return colorMap;
+}
+exports.buildSpanColorMap = buildSpanColorMap;
+/**
+ * Build a span color map from multiple spans.canvas files
+ * Later files override earlier ones for duplicate patterns
+ */
+function buildSpanColorMapFromCanvases(canvases) {
+    const colorMap = {};
+    for (const canvas of canvases) {
+        if (!canvas)
+            continue;
+        const conventions = extractSpanConventions(canvas);
+        for (const convention of conventions) {
+            colorMap[convention.spanPattern] = convention.color;
+        }
+    }
+    return colorMap;
+}
+exports.buildSpanColorMapFromCanvases = buildSpanColorMapFromCanvases;
+/**
+ * Match a span name to a span pattern
+ * Supports exact matches and wildcard patterns (e.g., "validate.*")
+ */
+function matchSpanPattern(spanName, pattern) {
+    // Exact match
+    if (spanName === pattern)
+        return true;
+    // Wildcard pattern (e.g., "validate.*")
+    if (pattern.endsWith('.*')) {
+        const prefix = pattern.slice(0, -2);
+        return spanName.startsWith(prefix + '.') || spanName === prefix;
+    }
+    return false;
+}
+exports.matchSpanPattern = matchSpanPattern;
+/**
+ * Find the color for a span name by matching against span patterns
+ * Returns the first matching pattern's color, or default if none match
+ */
+function getSpanColor(spanName, spanColorMap) {
+    // First try exact match
+    if (spanColorMap[spanName]) {
+        return spanColorMap[spanName];
+    }
+    // Then try pattern matching
+    for (const [pattern, color] of Object.entries(spanColorMap)) {
+        if (matchSpanPattern(spanName, pattern)) {
+            return color;
+        }
+    }
+    return exports.DEFAULT_SPAN_COLOR;
+}
+exports.getSpanColor = getSpanColor;
+/**
+ * Resolve span color for an event based on its workflow's spanPattern
+ * This is the primary method for determining event fill color
+ */
+function resolveEventSpanColor(workflowSpanPattern, spanColorMap) {
+    if (!workflowSpanPattern)
+        return exports.DEFAULT_SPAN_COLOR;
+    // Direct lookup (pattern as key)
+    if (spanColorMap[workflowSpanPattern]) {
+        return spanColorMap[workflowSpanPattern];
+    }
+    return exports.DEFAULT_SPAN_COLOR;
+}
+exports.resolveEventSpanColor = resolveEventSpanColor;
+/**
+ * Build a span icon map from a spans.canvas
+ * Returns a map of spanPattern -> icon for fast lookups
+ */
+function buildSpanIconMap(canvas) {
+    const iconMap = {};
+    if (!canvas)
+        return iconMap;
+    const conventions = extractSpanConventions(canvas);
+    for (const convention of conventions) {
+        if (convention.icon) {
+            iconMap[convention.spanPattern] = convention.icon;
+        }
+    }
+    return iconMap;
+}
+exports.buildSpanIconMap = buildSpanIconMap;
+/**
+ * Find the icon for a span name by matching against span patterns
+ * Returns the first matching pattern's icon, or undefined if none match
+ */
+function getSpanIcon(spanName, spanIconMap) {
+    // First try exact match
+    if (spanIconMap[spanName]) {
+        return spanIconMap[spanName];
+    }
+    // Then try pattern matching
+    for (const [pattern, icon] of Object.entries(spanIconMap)) {
+        if (matchSpanPattern(spanName, pattern)) {
+            return icon;
+        }
+    }
+    return undefined;
+}
+exports.getSpanIcon = getSpanIcon;
+//# sourceMappingURL=utils.js.map

package/dist/spans/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/spans/utils.ts"],"names":[],"mappings":"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"}

package/dist/storage/topic-types.d.ts

@@ -0,0 +1,203 @@
+/**
+ * Canonical topic contract — the shapes every consumer of `~/.principal/topics`
+ * agrees on. Browser-safe (no `node:*`); the file-per-topic store that reads and
+ * writes these lives in `./node` (see `topicStore.ts`).
+ *
+ * A **topic** is a curated bundle of trails on one subject. Two distinct named
+ * shapes, split by id-namespace / ownership, with an explicit translation
+ * between them — NOT one shared shape. They share most field names, but `id`
+ * and `trailIds` live in different namespaces (local vs server), so passing one
+ * where the other is expected corrupts the trail foreign-keys.
+ *
+ * - {@link DraftTopic}     — locally-authored, what desktop persists + edits.
+ * - {@link PublishedTopic} — server-authoritative, what the server returns and
+ *                            mobile reads.
+ * - {@link publishedFromDraft} — the Draft -> Published projection (one-way;
+ *                            there is no reverse hydration).
+ *
+ * The shapes mirror the over-the-wire form used by the sharing API (web-ade) so
+ * a published topic and a locally stored one stay interchangeable on read. All
+ * timestamps are ISO 8601 strings because this contract crosses the desktop/web
+ * boundary.
+ */
+/**
+ * Status of a topic — a small structured axis plus optional human nuance.
+ *
+ * `state` is the machine-meaningful signal (drives badge color, sorting, and
+ * filtering). `label` is free-form text shown in place of the default per-state
+ * label. `waitingOn` describes an external blocker and is meaningful when
+ * `state` is `waiting`.
+ *
+ * The structured shape is deliberate: it lets automations check and resolve a
+ * blocker without parsing prose — e.g. flip `waiting` -> `paused` once `until`
+ * passes, or once a referenced PR merges.
+ */
+export interface TopicStatus {
+    /**
+     * Structured lifecycle axis, ordered by a feature's "aliveness" from nascent
+     * to retired. Readers treat an absent OR unrecognized `state` as
+     * `new-thought`, so legacy topics and renamed values need no migration.
+     */
+    state: 'new-thought' | 'working' | 'paused' | 'waiting' | 'done-for-now' | 'deprecated' | 'abandoned';
+    /** Free-form text shown in place of the default label for the state. */
+    label?: string;
+    /** External blocker description. Meaningful when `state` is `waiting`. */
+    waitingOn?: {
+        /** Human description of the blocker, e.g. "design sign-off". */
+        note?: string;
+        /** ISO 8601 — when the hold is expected to lift. */
+        until?: string;
+        /** Structured pointer to the thing being waited on, for automations. */
+        ref?: {
+            kind: 'url' | 'pr' | 'issue' | 'topic' | 'trail';
+            /** The address/id of the referenced thing. */
+            value: string;
+            /** Optional human label for display. */
+            title?: string;
+        };
+    };
+}
+/**
+ * An image attached to a topic — primarily a screenshot dragged into the
+ * description. Bytes live on the topic (referenced from the description via an
+ * `asset://<id>` markdown link), not inlined into the description string. A
+ * render-time resolver swaps `asset://<id>` for `url` (preferred) or a data-URL
+ * built from `data`, keeping a local (data-only) and a published (url-bearing)
+ * topic interchangeable on read.
+ *
+ * Local-only on a {@link DraftTopic}: assets are uploaded/resolved at publish
+ * time, so a {@link PublishedTopic} carries the resolved `url`, not raw `data`.
+ */
+export interface TopicAsset {
+    /** Content hash — free dedup and the stable `asset://` target. */
+    id: string;
+    /** MIME type, e.g. "image/png". */
+    mime: string;
+    /** Base64-encoded bytes. Present locally and on publish. */
+    data?: string;
+    /** Resolvable URL, when the bytes have been offloaded (e.g. to S3). */
+    url?: string;
+    /** Markdown alt text. */
+    alt?: string;
+    /** Origin metadata, for future re-capture / open-live affordances. */
+    source?: {
+        storyId?: string;
+        storybookUrl?: string;
+    };
+}
+/**
+ * GitHub identity of a topic's creator. Populated when a signed-in user
+ * authors a topic; left undefined for local-only topics created before
+ * sign-in. The server requires this on publish.
+ */
+export interface TopicCreator {
+    githubId: number;
+    githubLogin: string;
+}
+/**
+ * Locally-authored topic — the shape desktop persists to
+ * `~/.principal/topics/<id>.json` and edits.
+ *
+ * Local id namespace. `description` / `createdBy` are optional (a Draft may be
+ * authored before sign-in). Carries local-only {@link TopicAsset}s
+ * (`asset://<id>` screenshots, raw `data`). Has NO `visibility` — that's a
+ * published concept.
+ *
+ * A Draft keeps existing after publish (it can be in a "published state"); its
+ * link to the server identity lives in the desktop's `topics-sync.json`
+ * sidecar, not in this shape.
+ */
+export interface DraftTopic {
+    /** Unique identifier in the LOCAL id namespace. */
+    id: string;
+    /** Display title. */
+    title: string;
+    /** Optional markdown body. */
+    description?: string;
+    /** Ordered list of LOCAL trail ids — foreign keys into the local trail store. */
+    trailIds: string[];
+    /**
+     * Repositories this topic is about, as PURL strings (e.g.
+     * `pkg:github/owner/repo`). The topic's own source of truth for "which repos"
+     * — portable and machine-independent, matching `WorkspaceMembership.repositoryId`.
+     * Machine-local clone paths stay a workspace-membership concern and never
+     * appear here, so this round-trips across machines on publish/fetch.
+     */
+    repos?: string[];
+    /** ISO 8601. */
+    createdAt: string;
+    /** ISO 8601. */
+    updatedAt: string;
+    /** Creator identity; undefined for topics authored before sign-in. */
+    createdBy?: TopicCreator;
+    /** Optional workflow status. Absent reads as `new-thought`. */
+    status?: TopicStatus;
+    /** Local image attachments, referenced from the description via `asset://<id>`. */
+    assets?: TopicAsset[];
+}
+/**
+ * Server-authoritative topic — the shape the server returns and mobile reads.
+ *
+ * Remote id namespace. `description` / `createdBy` are required (publish is the
+ * validation gate). Carries `visibility`; assets have been resolved to `url`s.
+ *
+ * CAVEAT: "Published" means "has a server identity", NOT "public" — a
+ * PublishedTopic can be `visibility: 'private'`.
+ */
+export interface PublishedTopic {
+    /** Unique identifier in the REMOTE (server) id namespace. */
+    id: string;
+    /** Display title. */
+    title: string;
+    /** Markdown body — required on the server. */
+    description: string;
+    /** Ordered list of REMOTE trail ids. */
+    trailIds: string[];
+    /**
+     * Repositories this topic is about, as PURL strings (e.g.
+     * `pkg:github/owner/repo`). Travels with the topic across the wire so a
+     * received shared topic carries its repos; preserved on publish/fetch.
+     */
+    repos?: string[];
+    /** ISO 8601. */
+    createdAt: string;
+    /** ISO 8601. */
+    updatedAt: string;
+    /** Creator identity — required on the server. */
+    createdBy: TopicCreator;
+    /** Optional workflow status, travels with the topic when published. */
+    status?: TopicStatus;
+    /** Server visibility. "private" is still a PublishedTopic. */
+    visibility: 'private' | 'public';
+}
+/**
+ * Inputs the {@link DraftTopic} cannot supply on its own — the namespace
+ * crossing and the fields publish must enforce. The caller resolves these
+ * before projecting:
+ * - `trailIds`: LOCAL trail ids remapped to REMOTE ids (web-ade references
+ *   trails by their server id; see desktop's `resolveRemoteTrailIds`).
+ * - `createdBy`: required on the server; supplied here if the draft lacks it.
+ * - `visibility`: a published concept the draft never carries.
+ */
+export interface PublishProjection {
+    trailIds: string[];
+    createdBy: TopicCreator;
+    visibility: 'private' | 'public';
+}
+/**
+ * Project a {@link DraftTopic} into a {@link PublishedTopic} — the one-way
+ * Draft -> Published translation. It does NOT perform any I/O (no id minting,
+ * no asset upload, no network): the caller resolves the namespace-crossing and
+ * required fields into {@link PublishProjection} first (remapping trail ids,
+ * uploading assets, choosing visibility), and this enforces the shape.
+ *
+ * One-way by design: there is no reverse `PublishedTopic -> DraftTopic`
+ * hydration. A published topic's edits write through to the server; the local
+ * Draft is reconciled from the server's response field-by-field, never by
+ * rebuilding a Draft from a Published shape.
+ *
+ * Throws if `description` is empty — publish is also the validation gate, and
+ * the server rejects a description-less topic.
+ */
+export declare function publishedFromDraft(draft: DraftTopic, projection: PublishProjection): PublishedTopic;
+//# sourceMappingURL=topic-types.d.ts.map

package/dist/storage/topic-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"topic-types.d.ts","sourceRoot":"","sources":["../../src/storage/topic-types.ts"],"names":[],"mappings":"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"}

package/dist/storage/topic-types.js

@@ -0,0 +1,60 @@
+"use strict";
+/**
+ * Canonical topic contract — the shapes every consumer of `~/.principal/topics`
+ * agrees on. Browser-safe (no `node:*`); the file-per-topic store that reads and
+ * writes these lives in `./node` (see `topicStore.ts`).
+ *
+ * A **topic** is a curated bundle of trails on one subject. Two distinct named
+ * shapes, split by id-namespace / ownership, with an explicit translation
+ * between them — NOT one shared shape. They share most field names, but `id`
+ * and `trailIds` live in different namespaces (local vs server), so passing one
+ * where the other is expected corrupts the trail foreign-keys.
+ *
+ * - {@link DraftTopic}     — locally-authored, what desktop persists + edits.
+ * - {@link PublishedTopic} — server-authoritative, what the server returns and
+ *                            mobile reads.
+ * - {@link publishedFromDraft} — the Draft -> Published projection (one-way;
+ *                            there is no reverse hydration).
+ *
+ * The shapes mirror the over-the-wire form used by the sharing API (web-ade) so
+ * a published topic and a locally stored one stay interchangeable on read. All
+ * timestamps are ISO 8601 strings because this contract crosses the desktop/web
+ * boundary.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.publishedFromDraft = void 0;
+/**
+ * Project a {@link DraftTopic} into a {@link PublishedTopic} — the one-way
+ * Draft -> Published translation. It does NOT perform any I/O (no id minting,
+ * no asset upload, no network): the caller resolves the namespace-crossing and
+ * required fields into {@link PublishProjection} first (remapping trail ids,
+ * uploading assets, choosing visibility), and this enforces the shape.
+ *
+ * One-way by design: there is no reverse `PublishedTopic -> DraftTopic`
+ * hydration. A published topic's edits write through to the server; the local
+ * Draft is reconciled from the server's response field-by-field, never by
+ * rebuilding a Draft from a Published shape.
+ *
+ * Throws if `description` is empty — publish is also the validation gate, and
+ * the server rejects a description-less topic.
+ */
+function publishedFromDraft(draft, projection) {
+    const description = (draft.description ?? '').trim();
+    if (description.length === 0) {
+        throw new Error(`Topic ${draft.id} has no description; a description is required to publish.`);
+    }
+    return {
+        id: draft.id,
+        title: draft.title,
+        description,
+        trailIds: projection.trailIds,
+        ...(draft.repos !== undefined ? { repos: draft.repos } : {}),
+        createdAt: draft.createdAt,
+        updatedAt: draft.updatedAt,
+        createdBy: projection.createdBy,
+        ...(draft.status !== undefined ? { status: draft.status } : {}),
+        visibility: projection.visibility,
+    };
+}
+exports.publishedFromDraft = publishedFromDraft;
+//# sourceMappingURL=topic-types.js.map

package/dist/storage/topic-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"topic-types.js","sourceRoot":"","sources":["../../src/storage/topic-types.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;;;AAgLH;;;;;;;;;;;;;;GAcG;AACH,SAAgB,kBAAkB,CAChC,KAAiB,EACjB,UAA6B;IAE7B,MAAM,WAAW,GAAG,CAAC,KAAK,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACrD,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC,EAAE;QAC5B,MAAM,IAAI,KAAK,CACb,SAAS,KAAK,CAAC,EAAE,4DAA4D,CAC9E,CAAC;KACH;IACD,OAAO;QACL,EAAE,EAAE,KAAK,CAAC,EAAE;QACZ,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,WAAW;QACX,QAAQ,EAAE,UAAU,CAAC,QAAQ;QAC7B,GAAG,CAAC,KAAK,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5D,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,SAAS,EAAE,UAAU,CAAC,SAAS;QAC/B,GAAG,CAAC,KAAK,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/D,UAAU,EAAE,UAAU,CAAC,UAAU;KAClC,CAAC;AACJ,CAAC;AAtBD,gDAsBC"}