@principal-ai/subsystems-core 0.29.0

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

@@ -0,0 +1,207 @@
+/**
+ * Resource Matching Types
+ *
+ * Defines how logs are matched to canvas nodes based on OTEL resource attributes.
+ * Supports multiple matching strategies: exact, glob, regex, existence, and oneOf.
+ *
+ * @example
+ * ```yaml
+ * # In canvas configuration
+ * nodes:
+ *   - id: "payment-service"
+ *     resourceMatch:
+ *       service.name: "payment-*"           # Glob pattern
+ *       deployment.environment: "production" # Exact match
+ *       db.system: { exists: true }         # Must have db.system attribute
+ * ```
+ */
+/**
+ * Exact match operator
+ *
+ * @example
+ * ```typescript
+ * const match: ExactMatch = { exact: 'checkout-api' };
+ * ```
+ */
+export interface ExactMatch {
+    exact: string;
+}
+/**
+ * Glob pattern match operator
+ * Supports * (any characters) and ? (single character)
+ *
+ * @example
+ * ```typescript
+ * const match: GlobMatch = { glob: 'payment-*' };  // matches payment-service, payment-worker
+ * const match2: GlobMatch = { glob: 'api-?' };     // matches api-1, api-2
+ * ```
+ */
+export interface GlobMatch {
+    glob: string;
+}
+/**
+ * Regex pattern match operator
+ *
+ * @example
+ * ```typescript
+ * const match: RegexMatch = { regex: '^checkout-.+$' };
+ * ```
+ */
+export interface RegexMatch {
+    regex: string;
+}
+/**
+ * Existence check operator
+ *
+ * @example
+ * ```typescript
+ * const mustExist: ExistsMatch = { exists: true };   // attribute must be present
+ * const mustNotExist: ExistsMatch = { exists: false }; // attribute must be absent
+ * ```
+ */
+export interface ExistsMatch {
+    exists: boolean;
+}
+/**
+ * OneOf match operator - matches any of the specified values
+ *
+ * @example
+ * ```typescript
+ * const match: OneOfMatch = { oneOf: ['production', 'staging'] };
+ * ```
+ */
+export interface OneOfMatch {
+    oneOf: string[];
+}
+/**
+ * Match operator union type
+ *
+ * Can be one of the structured operators or a plain string (shorthand for exact match).
+ *
+ * @example
+ * ```typescript
+ * // These are equivalent:
+ * const op1: MatchOperator = 'checkout-api';
+ * const op2: MatchOperator = { exact: 'checkout-api' };
+ *
+ * // Other operators:
+ * const glob: MatchOperator = { glob: 'payment-*' };
+ * const regex: MatchOperator = { regex: '^api-.+$' };
+ * const exists: MatchOperator = { exists: true };
+ * const oneOf: MatchOperator = { oneOf: ['prod', 'staging'] };
+ * ```
+ */
+export type MatchOperator = ExactMatch | GlobMatch | RegexMatch | ExistsMatch | OneOfMatch | string;
+/**
+ * Resource match criteria
+ *
+ * All specified conditions must match (AND logic).
+ * Use for defining which logs should route to a specific node.
+ *
+ * @example
+ * ```typescript
+ * const match: ResourceMatch = {
+ *   'service.name': 'checkout-api',              // Exact match (shorthand)
+ *   'deployment.environment': 'production',      // Exact match (shorthand)
+ *   'k8s.namespace.name': { glob: 'checkout-*' } // Glob pattern
+ * };
+ * ```
+ */
+export interface ResourceMatch {
+    'service.name'?: MatchOperator;
+    'service.namespace'?: MatchOperator;
+    'service.instance.id'?: MatchOperator;
+    'service.version'?: MatchOperator;
+    'deployment.environment'?: MatchOperator;
+    'k8s.namespace.name'?: MatchOperator;
+    'k8s.deployment.name'?: MatchOperator;
+    'k8s.pod.name'?: MatchOperator;
+    'k8s.container.name'?: MatchOperator;
+    'k8s.node.name'?: MatchOperator;
+    'db.system'?: MatchOperator;
+    'db.name'?: MatchOperator;
+    'host.name'?: MatchOperator;
+    'host.id'?: MatchOperator;
+    'cloud.provider'?: MatchOperator;
+    'cloud.region'?: MatchOperator;
+    'messaging.system'?: MatchOperator;
+    'messaging.destination.name'?: MatchOperator;
+    [key: string]: MatchOperator | undefined;
+}
+/**
+ * Result of a match attempt
+ *
+ * Includes the match outcome, specificity score for priority resolution,
+ * and details about which criteria matched or failed.
+ */
+export interface MatchResult {
+    /** Whether all criteria matched */
+    matched: boolean;
+    /**
+     * Match specificity score (higher = more specific match)
+     *
+     * Scoring rules:
+     * - Each exact match: +10 points
+     * - Each oneOf match: +8 points
+     * - Each regex match: +5 points
+     * - Each glob match: +3 points
+     * - Each exists match: +1 point
+     *
+     * Used to resolve conflicts when multiple nodes match the same log.
+     */
+    score: number;
+    /** List of criteria keys that matched */
+    matchedCriteria: string[];
+    /** List of criteria keys that failed (for debugging) */
+    failedCriteria?: string[];
+}
+/**
+ * Interface for nodes that support resource-based matching
+ *
+ * Nodes can have both resourceMatch (OTEL attributes) and sources (file paths).
+ * When routing logs, resourceMatch takes priority over sources.
+ */
+export interface ResourceMatchableNode {
+    /** Node identifier */
+    id: string;
+    /**
+     * Resource-based matching criteria (OTEL attributes)
+     * Takes priority over sources when both are specified.
+     */
+    resourceMatch?: ResourceMatch;
+    /**
+     * Path-based matching (source file globs)
+     * Used as fallback when resourceMatch is not specified or doesn't match.
+     * Also used for code coverage analysis.
+     */
+    sources?: string[];
+}
+/**
+ * Check if operator is an exact match
+ */
+export declare function isExactMatch(op: MatchOperator): op is ExactMatch;
+/**
+ * Check if operator is a glob match
+ */
+export declare function isGlobMatch(op: MatchOperator): op is GlobMatch;
+/**
+ * Check if operator is a regex match
+ */
+export declare function isRegexMatch(op: MatchOperator): op is RegexMatch;
+/**
+ * Check if operator is an exists match
+ */
+export declare function isExistsMatch(op: MatchOperator): op is ExistsMatch;
+/**
+ * Check if operator is a oneOf match
+ */
+export declare function isOneOfMatch(op: MatchOperator): op is OneOfMatch;
+/**
+ * Check if operator is a string shorthand (exact match)
+ */
+export declare function isStringShorthand(op: MatchOperator): op is string;
+/**
+ * Normalize a match operator to its canonical form
+ */
+export declare function normalizeOperator(op: MatchOperator): ExactMatch | GlobMatch | RegexMatch | ExistsMatch | OneOfMatch;
+//# sourceMappingURL=resource-match.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"resource-match.d.ts","sourceRoot":"","sources":["../../src/types/resource-match.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH;;;;;;;GAOG;AACH,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,SAAS,GAAG,UAAU,GAAG,WAAW,GAAG,UAAU,GAAG,MAAM,CAAC;AAEpG;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,aAAa;IAE5B,cAAc,CAAC,EAAE,aAAa,CAAC;IAC/B,mBAAmB,CAAC,EAAE,aAAa,CAAC;IACpC,qBAAqB,CAAC,EAAE,aAAa,CAAC;IACtC,iBAAiB,CAAC,EAAE,aAAa,CAAC;IAGlC,wBAAwB,CAAC,EAAE,aAAa,CAAC;IAGzC,oBAAoB,CAAC,EAAE,aAAa,CAAC;IACrC,qBAAqB,CAAC,EAAE,aAAa,CAAC;IACtC,cAAc,CAAC,EAAE,aAAa,CAAC;IAC/B,oBAAoB,CAAC,EAAE,aAAa,CAAC;IACrC,eAAe,CAAC,EAAE,aAAa,CAAC;IAGhC,WAAW,CAAC,EAAE,aAAa,CAAC;IAC5B,SAAS,CAAC,EAAE,aAAa,CAAC;IAG1B,WAAW,CAAC,EAAE,aAAa,CAAC;IAC5B,SAAS,CAAC,EAAE,aAAa,CAAC;IAG1B,gBAAgB,CAAC,EAAE,aAAa,CAAC;IACjC,cAAc,CAAC,EAAE,aAAa,CAAC;IAG/B,kBAAkB,CAAC,EAAE,aAAa,CAAC;IACnC,4BAA4B,CAAC,EAAE,aAAa,CAAC;IAG7C,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAAC;CAC1C;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,mCAAmC;IACnC,OAAO,EAAE,OAAO,CAAC;IAEjB;;;;;;;;;;;OAWG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd,yCAAyC;IACzC,eAAe,EAAE,MAAM,EAAE,CAAC;IAE1B,wDAAwD;IACxD,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC,sBAAsB;IACtB,EAAE,EAAE,MAAM,CAAC;IAEX;;;OAGG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC;IAE9B;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAID;;GAEG;AACH,wBAAgB,YAAY,CAAC,EAAE,EAAE,aAAa,GAAG,EAAE,IAAI,UAAU,CAEhE;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,aAAa,GAAG,EAAE,IAAI,SAAS,CAE9D;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,EAAE,EAAE,aAAa,GAAG,EAAE,IAAI,UAAU,CAEhE;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,EAAE,EAAE,aAAa,GAAG,EAAE,IAAI,WAAW,CAElE;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,EAAE,EAAE,aAAa,GAAG,EAAE,IAAI,UAAU,CAEhE;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,aAAa,GAAG,EAAE,IAAI,MAAM,CAEjE;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,EAAE,EAAE,aAAa,GAChB,UAAU,GAAG,SAAS,GAAG,UAAU,GAAG,WAAW,GAAG,UAAU,CAKhE"}

package/dist/types/resource-match.js

@@ -0,0 +1,74 @@
+"use strict";
+/**
+ * Resource Matching Types
+ *
+ * Defines how logs are matched to canvas nodes based on OTEL resource attributes.
+ * Supports multiple matching strategies: exact, glob, regex, existence, and oneOf.
+ *
+ * @example
+ * ```yaml
+ * # In canvas configuration
+ * nodes:
+ *   - id: "payment-service"
+ *     resourceMatch:
+ *       service.name: "payment-*"           # Glob pattern
+ *       deployment.environment: "production" # Exact match
+ *       db.system: { exists: true }         # Must have db.system attribute
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeOperator = exports.isStringShorthand = exports.isOneOfMatch = exports.isExistsMatch = exports.isRegexMatch = exports.isGlobMatch = exports.isExactMatch = void 0;
+// Type guards for match operators
+/**
+ * Check if operator is an exact match
+ */
+function isExactMatch(op) {
+    return typeof op === 'object' && 'exact' in op;
+}
+exports.isExactMatch = isExactMatch;
+/**
+ * Check if operator is a glob match
+ */
+function isGlobMatch(op) {
+    return typeof op === 'object' && 'glob' in op;
+}
+exports.isGlobMatch = isGlobMatch;
+/**
+ * Check if operator is a regex match
+ */
+function isRegexMatch(op) {
+    return typeof op === 'object' && 'regex' in op;
+}
+exports.isRegexMatch = isRegexMatch;
+/**
+ * Check if operator is an exists match
+ */
+function isExistsMatch(op) {
+    return typeof op === 'object' && 'exists' in op;
+}
+exports.isExistsMatch = isExistsMatch;
+/**
+ * Check if operator is a oneOf match
+ */
+function isOneOfMatch(op) {
+    return typeof op === 'object' && 'oneOf' in op;
+}
+exports.isOneOfMatch = isOneOfMatch;
+/**
+ * Check if operator is a string shorthand (exact match)
+ */
+function isStringShorthand(op) {
+    return typeof op === 'string';
+}
+exports.isStringShorthand = isStringShorthand;
+/**
+ * Normalize a match operator to its canonical form
+ */
+function normalizeOperator(op) {
+    if (typeof op === 'string') {
+        return { exact: op };
+    }
+    return op;
+}
+exports.normalizeOperator = normalizeOperator;
+//# sourceMappingURL=resource-match.js.map

package/dist/types/resource-match.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-match.js","sourceRoot":"","sources":["../../src/types/resource-match.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;GAgBG;;;AAgMH,kCAAkC;AAElC;;GAEG;AACH,SAAgB,YAAY,CAAC,EAAiB;IAC5C,OAAO,OAAO,EAAE,KAAK,QAAQ,IAAI,OAAO,IAAI,EAAE,CAAC;AACjD,CAAC;AAFD,oCAEC;AAED;;GAEG;AACH,SAAgB,WAAW,CAAC,EAAiB;IAC3C,OAAO,OAAO,EAAE,KAAK,QAAQ,IAAI,MAAM,IAAI,EAAE,CAAC;AAChD,CAAC;AAFD,kCAEC;AAED;;GAEG;AACH,SAAgB,YAAY,CAAC,EAAiB;IAC5C,OAAO,OAAO,EAAE,KAAK,QAAQ,IAAI,OAAO,IAAI,EAAE,CAAC;AACjD,CAAC;AAFD,oCAEC;AAED;;GAEG;AACH,SAAgB,aAAa,CAAC,EAAiB;IAC7C,OAAO,OAAO,EAAE,KAAK,QAAQ,IAAI,QAAQ,IAAI,EAAE,CAAC;AAClD,CAAC;AAFD,sCAEC;AAED;;GAEG;AACH,SAAgB,YAAY,CAAC,EAAiB;IAC5C,OAAO,OAAO,EAAE,KAAK,QAAQ,IAAI,OAAO,IAAI,EAAE,CAAC;AACjD,CAAC;AAFD,oCAEC;AAED;;GAEG;AACH,SAAgB,iBAAiB,CAAC,EAAiB;IACjD,OAAO,OAAO,EAAE,KAAK,QAAQ,CAAC;AAChC,CAAC;AAFD,8CAEC;AAED;;GAEG;AACH,SAAgB,iBAAiB,CAC/B,EAAiB;IAEjB,IAAI,OAAO,EAAE,KAAK,QAAQ,EAAE;QAC1B,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;KACtB;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAPD,8CAOC"}

package/dist/types/subsystem-model.d.ts

@@ -0,0 +1,265 @@
+/**
+ * Subsystem Model Types
+ *
+ * Two layers — do not conflate them:
+ *
+ * 1. **Portable document** (`SubsystemModelDocument`) — the shareable standard.
+ *    Schema: `schemas/subsystem-model.schema.json`
+ *    (`https://principal-ai.dev/schemas/subsystem-model.schema.json`).
+ *
+ * 2. **Hydrated envelope** (`SubsystemModelHydrated`) — portable document plus
+ *    host/machine binding (local roots, provenance, store ids, verification).
+ *    Used by viewers and stores; not part of the portable standard.
+ *
+ * Ontology: construct = what a node is, framework + stereotype = which
+ * framework pattern it plays, role = where it sits, process = where it runs.
+ * `symbol` is the code identity; `name` is the display label.
+ */
+/** What the node IS as a declaration. `module` is not an authored construct —
+ *  a module is its own subsystem. */
+export type SubsystemConstruct = 'class' | 'function' | 'method' | 'interface' | 'type_alias' | 'enum' | 'store' | 'external';
+/** Where the node sits in the topology, orthogonal to construct. */
+export type SubsystemComponentRole = 'entry' | 'service';
+/**
+ * Framework that owns a stereotype vocabulary (open string).
+ * Examples: `react`, `vue`, `nestjs`, `django`, `spring`.
+ * Empty when the node is language-only / framework-agnostic.
+ */
+export type SubsystemFramework = string;
+/**
+ * Framework-level pattern stamped on a language construct (open string).
+ * Examples: `component`, `hook`, `middleware`, `controller`, `guard`.
+ * Empty when no framework pattern applies. Pair with `framework` when set.
+ */
+export type SubsystemStereotype = string;
+/** How `from` relates to `to` on an edge. */
+export type SubsystemEdgeMechanism = 'imports' | 'imports_from' | 're_exports' | 'defines' | 'calls' | 'extends' | 'inherits' | 'implements' | 'mixes_in' | 'uses' | 'method' | 'references' | 'contains' | 'feeds' | 'produces' | 'writes' | 'reads' | 'watches' | 'registers-into';
+export type SubsystemCapture = 'edited' | 'analyzed' | 'referenced';
+export type SubsystemDeclarationProvenance = 'verified' | 'authored';
+export type SubsystemDeclTokenKind = 'keyword' | 'name' | 'member' | 'type' | 'punctuation' | 'string' | 'newline';
+export interface SubsystemDeclToken {
+    text: string;
+    kind: SubsystemDeclTokenKind;
+    /** Optional foreground when pre-tokenized for a theme. */
+    color?: string;
+}
+/** Anchored declaration location (usually from verify tooling). */
+export interface SubsystemDeclarationRef {
+    file: string;
+    startLine: number;
+    lineHash: string;
+    graphifyNodeId?: string;
+    capturedAt: string;
+    revision?: {
+        headSha: string;
+        dirtyHash?: string | null;
+    };
+}
+export interface SubsystemParamInfo {
+    name?: string;
+    type: string;
+    ref?: SubsystemReferenceInfo;
+}
+export interface SubsystemPropertyInfo {
+    name: string;
+    type?: string;
+    typeRef?: SubsystemReferenceInfo;
+    nodeId?: string;
+}
+export interface SubsystemMethodInfo {
+    nodeId: string;
+    name: string;
+    parameters?: SubsystemParamInfo[];
+    returnType?: string;
+    returnTypeRef?: SubsystemReferenceInfo;
+}
+export interface SubsystemCallInfo {
+    nodeId: string;
+    name: string;
+    source_location?: string;
+}
+export interface SubsystemReferenceInfo {
+    nodeId: string;
+    name: string;
+    context?: string;
+    source_location?: string;
+}
+export interface SubsystemImportInfo {
+    nodeId: string;
+    name: string;
+    relation?: string;
+    source_location?: string;
+}
+export interface SubsystemClassDeclaration {
+    kind: 'class';
+    methods: SubsystemMethodInfo[];
+    properties: SubsystemPropertyInfo[];
+    extends: string[];
+    implements: string[];
+    instantiations: SubsystemCallInfo[];
+    references: SubsystemReferenceInfo[];
+}
+export interface SubsystemFunctionDeclaration {
+    kind: 'function';
+    parameters: SubsystemParamInfo[];
+    returnType?: string;
+    returnTypeRef?: SubsystemReferenceInfo;
+    callers: SubsystemCallInfo[];
+    callees: SubsystemCallInfo[];
+}
+export interface SubsystemMethodDeclaration {
+    kind: 'method';
+    hostClass: string;
+    parameters?: SubsystemParamInfo[];
+    returnType?: string;
+}
+export interface SubsystemTypeDeclaration {
+    kind: 'type';
+    properties: SubsystemPropertyInfo[];
+    usedBy: SubsystemReferenceInfo[];
+    implementors: string[];
+}
+export interface SubsystemModuleDeclaration {
+    kind: 'module';
+    exports: string[];
+    imports: SubsystemImportInfo[];
+    symbols: string[];
+}
+export interface SubsystemExternalDeclaration {
+    kind: 'external';
+    label: string;
+}
+export interface SubsystemStoreDeclaration {
+    kind: 'store';
+    properties: SubsystemPropertyInfo[];
+}
+/** Structured declaration shape of a construct. */
+export type SubsystemConstructDeclaration = SubsystemClassDeclaration | SubsystemFunctionDeclaration | SubsystemMethodDeclaration | SubsystemTypeDeclaration | SubsystemModuleDeclaration | SubsystemExternalDeclaration | SubsystemStoreDeclaration;
+/** A component node — the named unit, construct-tagged. */
+export interface SubsystemComponent {
+    id: string;
+    /** Display label. Prefer aligning with `symbol` when present. */
+    name: string;
+    construct: SubsystemConstruct;
+    /** Repo-root-relative source path. */
+    file: string;
+    /** PURL for repo/package grouping. */
+    purl: string;
+    purpose?: string;
+    role?: SubsystemComponentRole;
+    /**
+     * Framework that owns the stereotype (e.g. `react`, `nestjs`).
+     * Orthogonal to `construct` — a React component is still `construct: function`.
+     */
+    framework?: SubsystemFramework;
+    /**
+     * Framework pattern this declaration plays (e.g. `component`, `hook`).
+     * Prefer this over inventing framework-specific constructs.
+     */
+    stereotype?: SubsystemStereotype;
+    process?: string;
+    /** Code identity — real declaration in `file` when set. */
+    symbol?: string;
+    layer?: number;
+    capture?: SubsystemCapture;
+    /** Structured declaration shape of the construct (params, members, …). */
+    declaration?: SubsystemConstructDeclaration;
+    declarationProvenance?: SubsystemDeclarationProvenance;
+    tokens?: SubsystemDeclToken[];
+    /** Location anchor (file/line/hash) — distinct from `declaration` (shape). */
+    declarationRef?: SubsystemDeclarationRef;
+}
+/** A cross-component edge. */
+export interface SubsystemComponentEdge {
+    id: string;
+    /** Source component id. */
+    from: string;
+    /** Target component id (or external label). */
+    to: string;
+    mechanism: SubsystemEdgeMechanism;
+    /** Concrete file/symbol evidence (often purls). */
+    refs?: string[];
+}
+export interface SubsystemThroughlineStep {
+    edgeId: string;
+    file: string;
+    /** 1-based line within `file`. */
+    line: number;
+    /** Frame name for this hop (function/method/symbol). Optional. */
+    symbol?: string;
+    /**
+     * Free-text note anchored to this hop's site line. Optional — informative
+     * only, never verified against source; viewers surface it via the codeview's
+     * annotation column.
+     */
+    annotation?: string;
+}
+/** Ordered execution story over existing edges (one per flow). */
+export interface SubsystemThroughline {
+    id: string;
+    title: string;
+    steps: SubsystemThroughlineStep[];
+}
+export interface SubsystemRepoRef {
+    owner: string;
+    name: string;
+}
+/**
+ * Portable subsystem model — the shareable standard.
+ * No host paths, provenance, document-level repo, store ids, or verification.
+ * Repo identity lives on each component's `purl`.
+ */
+export interface SubsystemModelDocument {
+    /**
+     * Optional pointer to the JSON Schema that describes this file. Lets editors
+     * give autocomplete and validation when the field is set.
+     */
+    $schema?: string;
+    title: string;
+    description?: string;
+    components: SubsystemComponent[];
+    edges: SubsystemComponentEdge[];
+    throughlines?: SubsystemThroughline[];
+}
+/**
+ * Host/machine fields layered onto a portable document for local use.
+ * Not part of the portable standard — viewers and stores own this envelope.
+ */
+export interface SubsystemModelHostBinding {
+    /** Provenance of the model (e.g. `agent:<name>`, `manual`). */
+    source?: string;
+    /**
+     * Optional document-level repo summary for host indexes/listings.
+     * Portable identity lives on each component's `purl`.
+     */
+    repo?: SubsystemRepoRef;
+    /**
+     * Local filesystem root component `file` paths resolve against.
+     * Opt-in; sandboxed reads for single-repo models.
+     */
+    repoRoot?: string;
+    /**
+     * Per-repo local roots for multi-repo models, keyed by purl repo key
+     * (`pkg:github/owner/name`, fragment stripped).
+     */
+    repoRoots?: Record<string, string>;
+}
+/**
+ * Hydrated model: portable document + host binding + optional store metadata.
+ * Shape used after a host accepts/persists a model for viewing on a machine.
+ */
+export interface SubsystemModelHydrated extends SubsystemModelDocument, SubsystemModelHostBinding {
+    /** Store-assigned id when persisted. */
+    id?: string;
+    createdAt?: string;
+    updatedAt?: string;
+    /** Host verification result; shape is host-defined. */
+    verification?: unknown;
+}
+/**
+ * Type guard: true when the value plausibly conforms to a portable
+ * subsystem model. Shallow check — full validation belongs to the schema /
+ * host validator.
+ */
+export declare function isSubsystemModelDocument(value: unknown): value is SubsystemModelDocument;
+//# sourceMappingURL=subsystem-model.d.ts.map

package/dist/types/subsystem-model.d.ts.map

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

package/dist/types/subsystem-model.js

@@ -0,0 +1,35 @@
+"use strict";
+/**
+ * Subsystem Model Types
+ *
+ * Two layers — do not conflate them:
+ *
+ * 1. **Portable document** (`SubsystemModelDocument`) — the shareable standard.
+ *    Schema: `schemas/subsystem-model.schema.json`
+ *    (`https://principal-ai.dev/schemas/subsystem-model.schema.json`).
+ *
+ * 2. **Hydrated envelope** (`SubsystemModelHydrated`) — portable document plus
+ *    host/machine binding (local roots, provenance, store ids, verification).
+ *    Used by viewers and stores; not part of the portable standard.
+ *
+ * Ontology: construct = what a node is, framework + stereotype = which
+ * framework pattern it plays, role = where it sits, process = where it runs.
+ * `symbol` is the code identity; `name` is the display label.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isSubsystemModelDocument = void 0;
+/**
+ * Type guard: true when the value plausibly conforms to a portable
+ * subsystem model. Shallow check — full validation belongs to the schema /
+ * host validator.
+ */
+function isSubsystemModelDocument(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const v = value;
+    return (typeof v.title === 'string' &&
+        Array.isArray(v.components) &&
+        Array.isArray(v.edges));
+}
+exports.isSubsystemModelDocument = isSubsystemModelDocument;
+//# sourceMappingURL=subsystem-model.js.map

package/dist/types/subsystem-model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subsystem-model.js","sourceRoot":"","sources":["../../src/types/subsystem-model.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;GAgBG;;;AA8TH;;;;GAIG;AACH,SAAgB,wBAAwB,CAAC,KAAc;IACrD,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IACtD,MAAM,CAAC,GAAG,KAIT,CAAC;IACF,OAAO,CACL,OAAO,CAAC,CAAC,KAAK,KAAK,QAAQ;QAC3B,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC;QAC3B,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CACvB,CAAC;AACJ,CAAC;AAZD,4DAYC"}