@semiont/core 0.5.2 → 0.5.4

package/dist/locales.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Locale information
+ * Copied from SDK for frontend use
+ */
+export interface LocaleInfo {
+    code: string;
+    nativeName: string;
+    englishName: string;
+}
+export declare const LOCALES: readonly LocaleInfo[];
+/**
+ * Get locale information by code
+ */
+export declare function getLocaleInfo(code: string | undefined): LocaleInfo | undefined;
+/**
+ * Get the native name of a language by its locale code
+ */
+export declare function getLocaleNativeName(code: string | undefined): string | undefined;
+/**
+ * Get the English name of a language by its locale code
+ */
+export declare function getLocaleEnglishName(code: string | undefined): string | undefined;
+/**
+ * Format locale code for display as "Native Name (code)"
+ */
+export declare function formatLocaleDisplay(code: string | undefined): string | undefined;
+/**
+ * Get all supported locale codes
+ */
+export declare function getAllLocaleCodes(): readonly string[];
+//# sourceMappingURL=locales.d.ts.map

package/dist/locales.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"locales.d.ts","sourceRoot":"","sources":["../src/locales.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,eAAO,MAAM,OAAO,EAAE,SAAS,UAAU,EA8B/B,CAAC;AAOX;;GAEG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,CAG9E;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAEhF;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAEjF;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAOhF;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,SAAS,MAAM,EAAE,CAErD"}

package/dist/logger.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Logger interface for observability
+ *
+ * This interface is intentionally framework-agnostic to work with any logger
+ * (winston, pino, bunyan, or simple console).
+ *
+ * Example usage:
+ * ```typescript
+ * import winston from 'winston';
+ *
+ * const logger = winston.createLogger({
+ *   level: 'debug',
+ *   transports: [new winston.transports.Console()]
+ * });
+ *
+ * const service = new MyService(logger);
+ * ```
+ */
+export interface Logger {
+    debug(message: string, meta?: any): void;
+    info(message: string, meta?: any): void;
+    warn(message: string, meta?: any): void;
+    error(message: string, meta?: any): void;
+    child(meta: Record<string, any>): Logger;
+}
+/**
+ * Serialize an error value into a form that JSON.stringify can handle
+ * meaningfully.
+ *
+ * Winston's default JSON formatter serializes `Error` instances as `{}`
+ * because `message`, `stack`, and `name` are non-enumerable properties on
+ * the Error prototype. That means `logger.error('x', { error })` with a
+ * raw Error argument produces useless log lines like
+ * `{"error":{},"message":"x",...}`, throwing away the information you
+ * actually need to diagnose the failure.
+ *
+ * This helper extracts the parts you want to see in a log — name,
+ * message, stack, and cause — and leaves non-Error values alone (so
+ * strings, numbers, and plain objects pass through unchanged).
+ *
+ * ## Usage
+ *
+ * ```ts
+ * try {
+ *   await doSomething();
+ * } catch (error) {
+ *   logger.error('Something failed', { error: errField(error) });
+ * }
+ * ```
+ *
+ * Use this at every `logger.error` call site that includes an `error`
+ * field derived from a catch block. Raw `{ error }` without this helper
+ * is almost always a bug.
+ */
+export declare function errField(error: unknown): unknown;
+//# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,MAAM;IACrB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,GAAG,IAAI,CAAC;IACzC,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,GAAG,IAAI,CAAC;IACxC,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,GAAG,IAAI,CAAC;IACxC,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,GAAG,IAAI,CAAC;IACzC,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,CAAC;CAC1C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAUhD"}

package/dist/mime-utils.d.ts

@@ -0,0 +1,38 @@
+/**
+ * MIME type utilities for Semiont
+ *
+ * Initial support for:
+ * - text/plain
+ * - text/markdown
+ * - image/png
+ * - image/jpeg
+ * - application/pdf
+ */
+/**
+ * Map MIME type to file extension
+ */
+export declare function getExtensionForMimeType(mimeType: string): string;
+/**
+ * Detect if MIME type is an image (png or jpeg only for now)
+ */
+export declare function isImageMimeType(mimeType: string): boolean;
+/**
+ * Detect if MIME type is text-based (plain or markdown only for now)
+ */
+export declare function isTextMimeType(mimeType: string): boolean;
+/**
+ * Detect if MIME type is PDF
+ */
+export declare function isPdfMimeType(mimeType: string): boolean;
+/**
+ * Get category for MIME type (for routing to appropriate viewer)
+ *
+ * Categories represent annotation models, not file formats:
+ * - 'text': Text-based annotations (TextPositionSelector, TextQuoteSelector)
+ * - 'image': Spatial coordinate annotations (SvgSelector, FragmentSelector)
+ *
+ * PDFs use spatial coordinates for annotations, so they belong to 'image' category.
+ */
+export type MimeCategory = 'text' | 'image' | 'unsupported';
+export declare function getMimeCategory(mimeType: string): MimeCategory;
+//# sourceMappingURL=mime-utils.d.ts.map

package/dist/mime-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mime-utils.d.ts","sourceRoot":"","sources":["../src/mime-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAUhE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEzD;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAExD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEvD;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,OAAO,GAAG,aAAa,CAAC;AAE5D,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,YAAY,CAQ9D"}

package/dist/operators/burst-buffer.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Adaptive burst buffer RxJS operator.
+ *
+ * Passes the first event through immediately (zero latency for interactive use).
+ * If more events arrive within the burst window, switches to accumulate mode
+ * and flushes batches. Returns to passthrough mode after an idle period.
+ *
+ * Emits individual items (T) in passthrough mode and arrays (T[]) in batch mode.
+ * Consumers distinguish via Array.isArray().
+ *
+ * Threshold tuning:
+ *   burstWindowMs  — How long to wait for more events before flushing a batch.
+ *                    50ms is a good default: longer than event-loop jitter (~1-5ms)
+ *                    but short enough to feel responsive.
+ *   maxBatchSize   — Force-flush at this size to bound memory. 500 is safe for
+ *                    Neo4j UNWIND queries. Increase if graph writes are cheap.
+ *   idleTimeoutMs  — How long after the last flush before returning to passthrough.
+ *                    200ms is a good default. Must be >= burstWindowMs.
+ *
+ * See: BATCH-GRAPH-CONSUMER-RX.md for design rationale.
+ * See: packages/graph/docs/ARCHITECTURE.md for graph consumer context.
+ */
+import { OperatorFunction } from 'rxjs';
+export interface BurstBufferOptions {
+    /**
+     * Time window (ms) to detect burst activity after an event.
+     * If another event arrives within this window, it is buffered.
+     * The buffer flushes when no new event arrives for this duration (debounce).
+     *
+     * Recommended: 50ms.
+     */
+    burstWindowMs: number;
+    /**
+     * Maximum events to accumulate before forcing a flush.
+     * Prevents unbounded memory growth during sustained bursts.
+     *
+     * Recommended: 500.
+     */
+    maxBatchSize: number;
+    /**
+     * Time (ms) of silence after the last flush before returning to passthrough mode.
+     * The next event after this timeout emits immediately (leading edge).
+     * Must be >= burstWindowMs.
+     *
+     * Recommended: 200ms.
+     */
+    idleTimeoutMs: number;
+}
+/**
+ * Adaptive burst buffer operator.
+ *
+ * State machine:
+ *   PASSTHROUGH → event arrives → emit immediately, transition to ACCUMULATING
+ *   ACCUMULATING → event arrives → buffer it, reset burst timer
+ *   ACCUMULATING → burst timer fires (no new events for burstWindowMs) → flush buffer as T[]
+ *   ACCUMULATING → buffer reaches maxBatchSize → flush buffer as T[]
+ *   After flush → idle timer starts
+ *   Idle timer fires (no new events for idleTimeoutMs) → transition to PASSTHROUGH
+ */
+export declare function burstBuffer<T>(options: BurstBufferOptions): OperatorFunction<T, T | T[]>;
+//# sourceMappingURL=burst-buffer.d.ts.map

package/dist/operators/burst-buffer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"burst-buffer.d.ts","sourceRoot":"","sources":["../../src/operators/burst-buffer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAc,gBAAgB,EAAE,MAAM,MAAM,CAAC;AAEpD,MAAM,WAAW,kBAAkB;IACjC;;;;;;OAMG;IACH,aAAa,EAAE,MAAM,CAAC;IAEtB;;;;;OAKG;IACH,YAAY,EAAE,MAAM,CAAC;IAErB;;;;;;OAMG;IACH,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAC3B,OAAO,EAAE,kBAAkB,GAC1B,gBAAgB,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAmG9B"}

package/dist/payload-types.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Payload Type Aliases
+ *
+ * Convenience aliases for OpenAPI-generated schema types that are
+ * referenced across the codebase. Shorter than
+ * `components['schemas']['<Name>']` and carry intent.
+ *
+ * These aliases are not about the bus. They live here so that
+ * bus-protocol.ts can focus on channel-protocol concerns (EventMap,
+ * CHANNEL_SCHEMAS, scope classification).
+ */
+import type { components } from './types';
+export type Selector = components['schemas']['TextPositionSelector'] | components['schemas']['TextQuoteSelector'] | components['schemas']['SvgSelector'] | components['schemas']['FragmentSelector'];
+export type GatheredContext = components['schemas']['GatheredContext'];
+export type SelectionData = components['schemas']['SelectionData'];
+//# sourceMappingURL=payload-types.d.ts.map

package/dist/payload-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payload-types.d.ts","sourceRoot":"","sources":["../src/payload-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE1C,MAAM,MAAM,QAAQ,GAChB,UAAU,CAAC,SAAS,CAAC,CAAC,sBAAsB,CAAC,GAC7C,UAAU,CAAC,SAAS,CAAC,CAAC,mBAAmB,CAAC,GAC1C,UAAU,CAAC,SAAS,CAAC,CAAC,aAAa,CAAC,GACpC,UAAU,CAAC,SAAS,CAAC,CAAC,kBAAkB,CAAC,CAAC;AAE9C,MAAM,MAAM,eAAe,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,iBAAiB,CAAC,CAAC;AACvE,MAAM,MAAM,aAAa,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,eAAe,CAAC,CAAC"}

package/dist/persisted-events.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Persisted Events
+ *
+ * The 18 event types that get appended to the JSONL event log.
+ * Each maps a type string to its OpenAPI payload schema.
+ * The PersistedEvent union derives from this catalog.
+ */
+import type { components } from './types';
+import type { AnnotationId, ResourceId } from './identifiers';
+import type { Annotation } from './annotation-types';
+import type { EventBase } from './event-base';
+type AnnotationAddedPayload = components['schemas']['AnnotationAddedPayload'] & {
+    annotation: Annotation;
+};
+type AnnotationRemovedPayload = components['schemas']['AnnotationRemovedPayload'] & {
+    annotationId: AnnotationId;
+};
+type AnnotationBodyUpdatedPayload = components['schemas']['AnnotationBodyUpdatedPayload'] & {
+    annotationId: AnnotationId;
+};
+/**
+ * Maps each persisted event type string to its OpenAPI payload schema.
+ * Single source of truth for "what events get written to the log."
+ */
+type PersistedEventCatalog = {
+    'yield:created': components['schemas']['ResourceCreatedPayload'];
+    'yield:cloned': components['schemas']['ResourceClonedPayload'];
+    'yield:updated': components['schemas']['ResourceUpdatedPayload'];
+    'yield:moved': components['schemas']['ResourceMovedPayload'];
+    'yield:representation-added': components['schemas']['RepresentationAddedPayload'];
+    'yield:representation-removed': components['schemas']['RepresentationRemovedPayload'];
+    'mark:added': AnnotationAddedPayload;
+    'mark:removed': AnnotationRemovedPayload;
+    'mark:body-updated': AnnotationBodyUpdatedPayload;
+    'mark:archived': components['schemas']['ResourceArchivedPayload'];
+    'mark:unarchived': components['schemas']['ResourceUnarchivedPayload'];
+    'mark:entity-tag-added': components['schemas']['EntityTagChangedPayload'];
+    'mark:entity-tag-removed': components['schemas']['EntityTagChangedPayload'];
+    'frame:entity-type-added': components['schemas']['EntityTypeAddedPayload'];
+    'frame:tag-schema-added': components['schemas']['TagSchemaAddedPayload'];
+    'job:started': components['schemas']['JobStartedPayload'];
+    'job:progress': components['schemas']['JobProgressPayload'];
+    'job:completed': components['schemas']['JobCompletedPayload'];
+    'job:failed': components['schemas']['JobFailedPayload'];
+};
+/** System event types — persisted events that have no resourceId. */
+type SystemEventType = 'frame:entity-type-added' | 'frame:tag-schema-added';
+/** Extract the concrete persisted event type for a given type string. */
+export type EventOfType<K extends keyof PersistedEventCatalog> = K extends SystemEventType ? EventBase & {
+    type: K;
+    payload: PersistedEventCatalog[K];
+} : EventBase & {
+    type: K;
+    resourceId: ResourceId;
+    payload: PersistedEventCatalog[K];
+};
+/** The union of all 20 persisted event types. Discriminated on `type`. */
+export type PersistedEvent = {
+    [K in keyof PersistedEventCatalog]: EventOfType<K>;
+}[keyof PersistedEventCatalog];
+export type PersistedEventType = PersistedEvent['type'];
+/**
+ * Runtime list of every persisted event type.
+ *
+ * Single source of truth for code that needs to enumerate event types at
+ * runtime — most importantly the per-resource `events-stream` SSE route,
+ * which subscribes to all of them. The exhaustiveness check below makes
+ * it impossible to add a new member to `PersistedEventCatalog` without
+ * also adding it here: forgetting fails to typecheck rather than silently
+ * dropping the event from the events-stream.
+ */
+export declare const PERSISTED_EVENT_TYPES: readonly ["yield:created", "yield:cloned", "yield:updated", "yield:moved", "yield:representation-added", "yield:representation-removed", "mark:added", "mark:removed", "mark:body-updated", "mark:archived", "mark:unarchived", "mark:entity-tag-added", "mark:entity-tag-removed", "frame:entity-type-added", "frame:tag-schema-added", "job:started", "job:progress", "job:completed", "job:failed"];
+/** Input type for appendEvent — PersistedEvent without id/timestamp (assigned at persistence time). */
+export type EventInput = Omit<PersistedEvent, 'id' | 'timestamp'>;
+export {};
+//# sourceMappingURL=persisted-events.d.ts.map

package/dist/persisted-events.d.ts.map

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

package/dist/project.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Represents a Semiont project rooted at a given directory.
+ *
+ * Computes all paths — durable and ephemeral — once at construction time.
+ * XDG environment variables are read here and nowhere else.
+ *
+ * Durable paths (inside the project root, committed or repo-local):
+ *   eventsDir          — .semiont/events/      (system of record, committed)
+ *   representationsDir — representations/      (content store, committed)
+ *
+ * Ephemeral paths (outside the project root, never committed):
+ *   configDir      — $XDG_CONFIG_HOME/semiont/{name}/  (generated config for managed processes)
+ *   dataHome       — $XDG_DATA_HOME/semiont/{name}/   (persistent user data, e.g. database files)
+ *   stateDir        — $XDG_STATE_HOME/semiont/{name}/
+ *   embeddingsDir   — stateDir/embeddings/
+ *   projectionsDir  — stateDir/projections/
+ *   jobsDir         — stateDir/jobs/
+ *   backendLogsDir      — stateDir/backend/
+ *   backendAppLogFile   — backendLogsDir/app.log
+ *   backendErrorLogFile — backendLogsDir/error.log
+ *   runtimeDir      — $XDG_RUNTIME_DIR/semiont/{name}/  (or $TMPDIR fallback)
+ *   backendPidFile  — runtimeDir/backend.pid
+ *
+ * Note: frontend paths are NOT project-scoped. The frontend service is bundled
+ * with the CLI and uses fixed XDG paths keyed by "frontend", not project name.
+ * See apps/cli/src/platforms/posix/handlers/frontend-paths.ts.
+ */
+export declare class SemiontProject {
+    readonly root: string;
+    readonly name: string;
+    /** True if [git] sync = true in .semiont/config. When true, semiont stages
+     *  working-tree and event-log changes in the git index automatically. */
+    readonly gitSync: boolean;
+    readonly eventsDir: string;
+    readonly representationsDir: string;
+    readonly configDir: string;
+    readonly dataHome: string;
+    readonly stateDir: string;
+    readonly embeddingsDir: string;
+    readonly projectionsDir: string;
+    readonly jobsDir: string;
+    readonly backendLogsDir: string;
+    readonly backendAppLogFile: string;
+    readonly backendErrorLogFile: string;
+    readonly runtimeDir: string;
+    readonly backendPidFile: string;
+    constructor(projectRoot: string, name?: string);
+    /**
+     * Read the current git branch for the project root.
+     * Returns null if the project is not a git repo or git is not available.
+     */
+    gitBranch(): string | null;
+    /**
+     * Delete all ephemeral state for this project (stateDir + runtimeDir).
+     * Does not touch eventsDir or dataDir.
+     */
+    destroy(): Promise<void>;
+    /**
+     * Read [git] sync from .semiont/config.
+     * Defaults to false if the section or key is absent.
+     */
+    private static readGitSync;
+    /**
+     * Read the project name from .semiont/config [project] name = "..."
+     * Falls back to the directory basename if the config is absent or has no name.
+     */
+    private static readName;
+}
+//# sourceMappingURL=project.d.ts.map

package/dist/project.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project.d.ts","sourceRoot":"","sources":["../src/project.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,cAAc;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;6EACyE;IACzE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAG1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IAGpC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAG3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAG1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IAGrC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;gBAEpB,WAAW,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM;IAoC9C;;;OAGG;IACH,SAAS,IAAI,MAAM,GAAG,IAAI;IAY1B;;;OAGG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ9B;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,WAAW;IAiB1B;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ;CAcxB"}

package/dist/resource-types.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Resource input/output types
+ */
+export interface UpdateResourceInput {
+    name?: string;
+    entityTypes?: string[];
+    archived?: boolean;
+}
+export interface ResourceFilter {
+    entityTypes?: string[];
+    search?: string;
+    limit?: number;
+    offset?: number;
+}
+//# sourceMappingURL=resource-types.d.ts.map

package/dist/resource-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-types.d.ts","sourceRoot":"","sources":["../src/resource-types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,mBAAmB;IAClC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,cAAc;IAC7B,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB"}

package/dist/resource-utils.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Helper functions for working with W3C ResourceDescriptor
+ */
+import type { components } from './types';
+import type { ResourceDescriptor } from './graph';
+type Representation = components['schemas']['Representation'];
+/**
+ * Get the resource ID from @id property
+ *
+ * @id is always a bare ID (UUID), never a full URI.
+ */
+export declare function getResourceId(resource: ResourceDescriptor | undefined): string | undefined;
+/**
+ * Get the primary representation (first or only representation)
+ */
+export declare function getPrimaryRepresentation(resource: ResourceDescriptor | undefined): Representation | undefined;
+/**
+ * Get the media type from the primary representation
+ */
+export declare function getPrimaryMediaType(resource: ResourceDescriptor | undefined): string | undefined;
+/**
+ * Get the checksum from the primary representation
+ */
+export declare function getChecksum(resource: ResourceDescriptor | undefined): string | undefined;
+/**
+ * Get the language from the primary representation
+ */
+export declare function getLanguage(resource: ResourceDescriptor | undefined): string | undefined;
+/**
+ * Get storage URI from primary representation
+ *
+ * @param resource - ResourceDescriptor
+ * @returns Storage URI or undefined
+ */
+export declare function getStorageUri(resource: ResourceDescriptor | undefined): string | undefined;
+/**
+ * Get creator agent from wasAttributedTo
+ * Handles both single agent and array of agents
+ *
+ * @param resource - ResourceDescriptor
+ * @returns First agent or undefined
+ */
+export declare function getCreator(resource: ResourceDescriptor | undefined): components['schemas']['Agent'] | undefined;
+/**
+ * Get derived-from URI
+ * Handles both single URI and array of URIs
+ *
+ * @param resource - ResourceDescriptor
+ * @returns First derivation URI or undefined
+ */
+export declare function getDerivedFrom(resource: ResourceDescriptor | undefined): string | undefined;
+/**
+ * Check if resource is archived (application-specific field)
+ *
+ * @param resource - ResourceDescriptor
+ * @returns True if archived, false otherwise
+ */
+export declare function isArchived(resource: ResourceDescriptor | undefined): boolean;
+/**
+ * Get entity types from resource (application-specific field)
+ *
+ * @param resource - ResourceDescriptor
+ * @returns Array of entity types, empty if not set
+ */
+export declare function getResourceEntityTypes(resource: ResourceDescriptor | undefined): string[];
+/**
+ * Check if resource is a draft (application-specific field)
+ *
+ * @param resource - ResourceDescriptor
+ * @returns True if draft, false otherwise
+ */
+export declare function isDraft(resource: ResourceDescriptor | undefined): boolean;
+/**
+ * Map charset names to Node.js Buffer encoding names
+ * Node.js Buffer.toString() supports: 'utf8', 'utf16le', 'latin1', 'base64', 'hex', 'ascii', 'binary', 'ucs2'
+ *
+ * @param charset - Charset name (e.g., "UTF-8", "ISO-8859-1", "Windows-1252")
+ * @returns Node.js BufferEncoding
+ */
+export declare function getNodeEncoding(charset: string): BufferEncoding;
+/**
+ * Decode a representation buffer to string using the correct charset
+ * Extracts charset from media type and uses appropriate encoding
+ *
+ * @param buffer - The raw representation data
+ * @param mediaType - Media type with optional charset (e.g., "text/plain; charset=iso-8859-1")
+ * @returns Decoded string
+ *
+ * @example
+ * ```typescript
+ * const content = decodeRepresentation(buffer, "text/plain; charset=utf-8");
+ * const legacy = decodeRepresentation(buffer, "text/plain; charset=windows-1252");
+ * ```
+ */
+export declare function decodeRepresentation(buffer: Buffer, mediaType: string): string;
+export {};
+//# sourceMappingURL=resource-utils.d.ts.map

package/dist/resource-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-utils.d.ts","sourceRoot":"","sources":["../src/resource-utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAC1C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAElD,KAAK,cAAc,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,gBAAgB,CAAC,CAAC;AAE9D;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,kBAAkB,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAG1F;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,kBAAkB,GAAG,SAAS,GAAG,cAAc,GAAG,SAAS,CAM7G;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,kBAAkB,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAEhG;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,kBAAkB,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAExF;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,kBAAkB,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAExF;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,kBAAkB,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAE1F;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,kBAAkB,GAAG,SAAS,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,OAAO,CAAC,GAAG,SAAS,CAM/G;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,kBAAkB,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAM3F;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,kBAAkB,GAAG,SAAS,GAAG,OAAO,CAE5E;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,kBAAkB,GAAG,SAAS,GAAG,MAAM,EAAE,CAEzF;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,QAAQ,EAAE,kBAAkB,GAAG,SAAS,GAAG,OAAO,CAEzE;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,CAkB/D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAS9E"}

package/dist/serialize-per-key.d.ts

@@ -0,0 +1,51 @@
+/**
+ * serializePerKey — run async work serialized per key, parallel across keys.
+ *
+ * Invariant: two calls with the same `key` run strictly in sequence (the
+ * second `work` does not start until the first has settled). Calls with
+ * different keys overlap freely.
+ *
+ * Error isolation: a rejected work function does not poison subsequent
+ * tasks for the same key. The next task starts fresh from whatever state
+ * the failed task left behind. The rejection still propagates to *this*
+ * caller.
+ *
+ * Registry cleanup: the entry for a key is removed as soon as its chain
+ * empties, so the Map stays bounded by the number of keys with work
+ * currently in flight, not by the total number of keys ever seen.
+ *
+ * ## Usage
+ *
+ * ```ts
+ * const chains = new Map<string, Promise<void>>();
+ *
+ * async function write(resourceId: string, event: Event) {
+ *   return serializePerKey(resourceId, chains, async () => {
+ *     // Read-modify-write on a view file. Any two concurrent calls with
+ *     // the same resourceId will be serialized; different resourceIds
+ *     // will proceed in parallel.
+ *     const view = await viewStorage.get(resourceId);
+ *     applyEvent(view, event);
+ *     await viewStorage.save(resourceId, view);
+ *   });
+ * }
+ * ```
+ *
+ * ## When to use this vs RxJS `groupBy + concatMap`
+ *
+ * Use `serializePerKey` when the work arrives as **direct method calls**
+ * that need to block the caller until completion. This is the RPC shape
+ * — think `EventStore.appendEvent` calling `await views.materializeResource(...)`
+ * and needing the view written before any subscriber sees the published
+ * event.
+ *
+ * Use RxJS `groupBy(keyFn) + concatMap(...)` when the work arrives as an
+ * **event stream** that a component subscribes to once at startup. This
+ * is how `Smelter`, `GraphDBConsumer`, and `Gatherer` serialize their own
+ * per-resource work — see their implementations in `packages/make-meaning`.
+ *
+ * Both patterns solve the same logical problem ("serialize work per key").
+ * The choice is dictated by whether the caller is awaiting the result.
+ */
+export declare function serializePerKey<K, T>(key: K, chains: Map<K, Promise<void>>, work: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=serialize-per-key.d.ts.map

package/dist/serialize-per-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialize-per-key.d.ts","sourceRoot":"","sources":["../src/serialize-per-key.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,wBAAsB,eAAe,CAAC,CAAC,EAAE,CAAC,EACxC,GAAG,EAAE,CAAC,EACN,MAAM,EAAE,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC,EAC7B,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACrB,OAAO,CAAC,CAAC,CAAC,CAyBZ"}

package/dist/svg-utils.d.ts

@@ -0,0 +1,44 @@
+/**
+ * SVG Utility Functions
+ *
+ * Utilities for creating, parsing, and manipulating W3C-compliant SVG selectors
+ * for image annotation.
+ */
+export interface Point {
+    x: number;
+    y: number;
+}
+export interface BoundingBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * Create W3C-compliant SVG rectangle selector
+ */
+export declare function createRectangleSvg(start: Point, end: Point): string;
+/**
+ * Create W3C-compliant SVG polygon selector
+ */
+export declare function createPolygonSvg(points: Point[]): string;
+/**
+ * Create W3C-compliant SVG circle selector
+ */
+export declare function createCircleSvg(center: Point, radius: number): string;
+/**
+ * Parse SVG selector to extract shape type and data
+ */
+export declare function parseSvgSelector(svg: string): {
+    type: 'rect' | 'polygon' | 'circle' | 'path';
+    data: any;
+} | null;
+/**
+ * Normalize coordinates from display space to image native resolution
+ */
+export declare function normalizeCoordinates(point: Point, displayWidth: number, displayHeight: number, imageWidth: number, imageHeight: number): Point;
+/**
+ * Scale entire SVG selector from display space to image native resolution
+ */
+export declare function scaleSvgToNative(svg: string, displayWidth: number, displayHeight: number, imageWidth: number, imageHeight: number): string;
+//# sourceMappingURL=svg-utils.d.ts.map

package/dist/svg-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"svg-utils.d.ts","sourceRoot":"","sources":["../src/svg-utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,KAAK;IACpB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAED,MAAM,WAAW,WAAW;IAC1B,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,GAAG,MAAM,CAOnE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,CAOxD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAMrE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG;IAC7C,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,MAAM,CAAC;IAC7C,IAAI,EAAE,GAAG,CAAC;CACX,GAAG,IAAI,CA8CP;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,KAAK,EACZ,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,MAAM,EACrB,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,GAClB,KAAK,CAKP;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,MAAM,EACX,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,MAAM,EACrB,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,GAClB,MAAM,CAkCR"}

package/dist/tag-schemas.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Tag-schema type aliases.
+ *
+ * These are type-only re-exports of the OpenAPI `TagSchema` and `TagCategory`
+ * shapes. The schemas themselves do not live in `@semiont/core` — they're
+ * registered at runtime per-KB via `frame.addTagSchema(...)` against a
+ * per-KB projection. This module just exposes the shape so KB authors and
+ * skill code can type their schema literals without the OpenAPI lookup
+ * syntax (`components['schemas']['TagSchema']`).
+ */
+import type { components } from './types';
+/**
+ * A structural-analysis schema (e.g. legal-irac, scientific-imrad).
+ *
+ * Defines a methodology framework as an id, name, description, domain hint,
+ * and an ordered list of categories. KBs and their skills register schemas
+ * with the runtime registry via `frame.addTagSchema(...)` at session start.
+ */
+export type TagSchema = components['schemas']['TagSchema'];
+/**
+ * A single category within a {@link TagSchema} (e.g. 'Issue' in IRAC).
+ *
+ * Each category carries methodology-bound semantics: a name, a description,
+ * and examples used in the LLM prompt.
+ */
+export type TagCategory = components['schemas']['TagCategory'];
+//# sourceMappingURL=tag-schemas.d.ts.map

package/dist/tag-schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tag-schemas.d.ts","sourceRoot":"","sources":["../src/tag-schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE1C;;;;;;GAMG;AACH,MAAM,MAAM,SAAS,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,WAAW,CAAC,CAAC;AAE3D;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,aAAa,CAAC,CAAC"}