@principal-ai/subsystems-core 0.29.0

package/dist/agent-sessions/fixture.js

@@ -0,0 +1,130 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildAgentSessionFixture = void 0;
+const node_path_1 = __importDefault(require("node:path"));
+const agent_monitoring_1 = require("@principal-ai/agent-monitoring");
+function repoLabel(nf) {
+    if (nf.repository?.repo)
+        return nf.repository.repo;
+    if (nf.repository?.gitRoot)
+        return node_path_1.default.basename(nf.repository.gitRoot);
+    return "";
+}
+function repoRoot(nf) {
+    return nf.repository?.gitRoot ?? "";
+}
+/**
+ * Extract a model id from a model value — agents set it inconsistently
+ * (opencode stores `{ providerID, modelID }`-shaped objects, cline / grok /
+ * pi store a plain string id).
+ */
+function modelIdOf(value) {
+    if (typeof value === "string" && value.length > 0)
+        return value;
+    if (value && typeof value === "object") {
+        const o = value;
+        for (const key of ["modelID", "id"]) {
+            if (typeof o[key] === "string" && o[key].length > 0) {
+                return o[key];
+            }
+        }
+    }
+    return undefined;
+}
+/** Pull the model id from one event — normalized `data.model` first, then the
+ *  raw opencode `info` blob (the bridge only copies `info.model` onto
+ *  normalized events when the session's created event carried it). */
+function eventModelId(e) {
+    const direct = modelIdOf(e.data?.["model"]);
+    if (direct)
+        return direct;
+    const raw = e.raw;
+    return modelIdOf(raw?.data?.info?.model);
+}
+/** Distinct model ids across a session's events, in first-seen order. */
+function collectModels(events) {
+    const seen = new Set();
+    const models = [];
+    for (const e of events) {
+        const id = eventModelId(e);
+        if (id && !seen.has(id)) {
+            seen.add(id);
+            models.push(id);
+        }
+    }
+    return models;
+}
+function buildAgentSessionFixture(options) {
+    const { agent, sessionId, sessionMeta, normalizedEvents, rawEventCount } = options;
+    const sessionName = sessionMeta.sessionName || "opencode";
+    const agentEvents = (0, agent_monitoring_1.accumulateToAgentSessionEvents)(normalizedEvents, sessionName);
+    // Rewrite layer item paths (repo-relative displayPath) back to absolute
+    // paths. Layer snapshots reflect accumulated state across events, so build a
+    // global displayPath -> absolutePath map from every event's files/dependencies.
+    const repoBreakdown = new Map();
+    const displayToAbs = new Map();
+    for (const e of agentEvents) {
+        for (const f of [...e.files, ...e.dependencies]) {
+            if (typeof f === "object" && f && "displayPath" in f) {
+                const nf = f;
+                if (nf.displayPath && !displayToAbs.has(nf.displayPath)) {
+                    displayToAbs.set(nf.displayPath, nf.absolutePath);
+                }
+                const label = repoLabel(nf);
+                if (!repoBreakdown.has(label)) {
+                    repoBreakdown.set(label, { root: repoRoot(nf), files: new Set(), edits: new Set() });
+                }
+                repoBreakdown.get(label).files.add(nf.absolutePath);
+                if (!repoBreakdown.get(label).root)
+                    repoBreakdown.get(label).root = repoRoot(nf);
+            }
+        }
+    }
+    const events = agentEvents.map((e) => {
+        const files = e.files.map((f) => typeof f === "string" ? f : f.absolutePath);
+        const dependencies = e.dependencies.map((f) => typeof f === "string" ? f : f.absolutePath);
+        if (e.operation === "editing") {
+            for (const f of files) {
+                const label = [...repoBreakdown.entries()].find(([, v]) => v.files.has(f))?.[0] ?? "";
+                if (!repoBreakdown.has(label)) {
+                    repoBreakdown.set(label, { root: "", files: new Set(), edits: new Set() });
+                }
+                repoBreakdown.get(label).edits.add(f);
+            }
+        }
+        const layers = e.layers.map((l) => ({
+            ...l,
+            items: l.items.map((item) => {
+                const abs = item.path.startsWith("/") ? item.path : displayToAbs.get(item.path) ?? item.path;
+                return { ...item, path: abs };
+            }),
+        }));
+        return { ...e, files, dependencies, layers };
+    });
+    const session = {
+        sessionId,
+        agent,
+        sessionName,
+        sessionTask: sessionMeta.sessionTask,
+        workingDirectory: sessionMeta.workingDirectory,
+        rawEventCount: rawEventCount ?? normalizedEvents.length,
+        agentEventCount: events.length,
+        repos: [...repoBreakdown.entries()].map(([repo, v]) => ({
+            repo,
+            root: v.root,
+            files: v.files.size,
+            edits: v.edits.size,
+        })),
+        models: collectModels(normalizedEvents),
+    };
+    return {
+        generatedFrom: `${agent} session ${sessionId}`,
+        session,
+        events,
+    };
+}
+exports.buildAgentSessionFixture = buildAgentSessionFixture;
+//# sourceMappingURL=fixture.js.map

package/dist/agent-sessions/fixture.js.map

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

package/dist/agent-sessions/index.d.ts

@@ -0,0 +1,3 @@
+export { buildAgentSessionFixture } from "./fixture";
+export type { AgentSessionFixture, AgentSessionFixtureMeta, AgentSessionFixtureRepo, AgentSessionFixtureSummary, FixtureAgentSessionEvent, FixtureHighlightLayer, FixtureLayerItem, } from "./fixture";
+//# sourceMappingURL=index.d.ts.map

package/dist/agent-sessions/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agent-sessions/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,WAAW,CAAC;AACrD,YAAY,EACV,mBAAmB,EACnB,uBAAuB,EACvB,uBAAuB,EACvB,0BAA0B,EAC1B,wBAAwB,EACxB,qBAAqB,EACrB,gBAAgB,GACjB,MAAM,WAAW,CAAC"}

package/dist/agent-sessions/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildAgentSessionFixture = void 0;
+var fixture_1 = require("./fixture");
+Object.defineProperty(exports, "buildAgentSessionFixture", { enumerable: true, get: function () { return fixture_1.buildAgentSessionFixture; } });
+//# sourceMappingURL=index.js.map

package/dist/agent-sessions/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/agent-sessions/index.ts"],"names":[],"mappings":";;;AAAA,qCAAqD;AAA5C,mHAAA,wBAAwB,OAAA"}

package/dist/auxiliary/AuxiliaryManifestValidator.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Auxiliary Manifest Validator
+ *
+ * Own-file checks for `.principal-views/auxiliary.manifest.json`:
+ *   - area names are unique
+ *   - declared paths exist on disk
+ *   - paths don't overlap each other (within or across areas)
+ *
+ * Cross-file overlap with scope paths lives in `validateAreaScopeDisjoint`,
+ * mirroring the way `validateScopeNamespaceNesting` handles cross-canvas
+ * checks for scopes/namespaces.
+ */
+import type { FileSystemAdapter } from '@principal-ai/repository-abstraction';
+import type { AuxiliaryManifest } from '../types/auxiliary';
+export interface AuxiliaryManifestValidationContext {
+    /** Parsed manifest. When absent, validation is a no-op (manifest is optional). */
+    manifest?: AuxiliaryManifest;
+    /** Path to the manifest file — used in violation messages. */
+    manifestPath?: string;
+    /** Repo root for resolving area paths against the filesystem. */
+    basePath: string;
+}
+export interface AuxiliaryManifestViolation {
+    ruleId: string;
+    severity: 'error' | 'warn';
+    file: string;
+    path?: string;
+    message: string;
+    impact: string;
+    suggestion: string;
+}
+export interface AuxiliaryManifestValidationResult {
+    valid: boolean;
+    violations: AuxiliaryManifestViolation[];
+}
+export declare class AuxiliaryManifestValidator {
+    private fsAdapter;
+    constructor(fsAdapter: FileSystemAdapter);
+    validate(context: AuxiliaryManifestValidationContext): Promise<AuxiliaryManifestValidationResult>;
+}
+//# sourceMappingURL=AuxiliaryManifestValidator.d.ts.map

package/dist/auxiliary/AuxiliaryManifestValidator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AuxiliaryManifestValidator.d.ts","sourceRoot":"","sources":["../../src/auxiliary/AuxiliaryManifestValidator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sCAAsC,CAAC;AAC9E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAG5D,MAAM,WAAW,kCAAkC;IACjD,kFAAkF;IAClF,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAE7B,8DAA8D;IAC9D,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB,iEAAiE;IACjE,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,0BAA0B;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,OAAO,GAAG,MAAM,CAAC;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,iCAAiC;IAChD,KAAK,EAAE,OAAO,CAAC;IACf,UAAU,EAAE,0BAA0B,EAAE,CAAC;CAC1C;AAID,qBAAa,0BAA0B;IACzB,OAAO,CAAC,SAAS;gBAAT,SAAS,EAAE,iBAAiB;IAE1C,QAAQ,CAAC,OAAO,EAAE,kCAAkC,GAAG,OAAO,CAAC,iCAAiC,CAAC;CAmFxG"}

package/dist/auxiliary/AuxiliaryManifestValidator.js

@@ -0,0 +1,100 @@
+"use strict";
+/**
+ * Auxiliary Manifest Validator
+ *
+ * Own-file checks for `.principal-views/auxiliary.manifest.json`:
+ *   - area names are unique
+ *   - declared paths exist on disk
+ *   - paths don't overlap each other (within or across areas)
+ *
+ * Cross-file overlap with scope paths lives in `validateAreaScopeDisjoint`,
+ * mirroring the way `validateScopeNamespaceNesting` handles cross-canvas
+ * checks for scopes/namespaces.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuxiliaryManifestValidator = void 0;
+const path_helpers_1 = require("../events/path-helpers");
+const DEFAULT_MANIFEST_PATH = '.principal-views/auxiliary.manifest.json';
+class AuxiliaryManifestValidator {
+    constructor(fsAdapter) {
+        this.fsAdapter = fsAdapter;
+    }
+    async validate(context) {
+        const violations = [];
+        const { manifest, basePath } = context;
+        const file = context.manifestPath || DEFAULT_MANIFEST_PATH;
+        if (!manifest) {
+            return { valid: true, violations };
+        }
+        const areas = manifest.areas || [];
+        // Unique area names
+        const seenNames = new Map();
+        areas.forEach((area, idx) => {
+            const count = seenNames.get(area.name) ?? 0;
+            seenNames.set(area.name, count + 1);
+            if (count === 1) {
+                violations.push({
+                    ruleId: 'auxiliary-area-name-duplicate',
+                    severity: 'error',
+                    file,
+                    path: `areas[${idx}].name`,
+                    message: `Area name "${area.name}" is declared more than once`,
+                    impact: 'Duplicate names make diagnostics ambiguous — a violation cannot be tied back to a single area',
+                    suggestion: 'Rename one of the areas so names are unique across the manifest.',
+                });
+            }
+        });
+        // Path existence + collect for overlap pass
+        const declaredPaths = [];
+        for (let areaIdx = 0; areaIdx < areas.length; areaIdx++) {
+            const area = areas[areaIdx];
+            const paths = area.paths || [];
+            for (let pathIdx = 0; pathIdx < paths.length; pathIdx++) {
+                const p = paths[pathIdx];
+                declaredPaths.push({ areaName: area.name, areaIndex: areaIdx, pathIndex: pathIdx, path: p });
+                const resolved = this.fsAdapter.join(basePath, p);
+                if (!(await this.fsAdapter.exists(resolved))) {
+                    violations.push({
+                        ruleId: 'auxiliary-area-path-missing',
+                        severity: 'warn',
+                        file,
+                        path: `areas[${areaIdx}].paths[${pathIdx}]`,
+                        message: `Path "${p}" declared by area "${area.name}" does not exist`,
+                        impact: 'The manifest documents a folder that is not present in the repository',
+                        suggestion: 'Verify the path exists relative to the repository root, or remove it from the area declaration.',
+                    });
+                }
+            }
+        }
+        // Path overlap. Unlike scopes, areas have no dotted-name hierarchy, so
+        // parent-child nesting between two areas is just as ambiguous as a flat
+        // overlap — both are flagged.
+        for (let i = 0; i < declaredPaths.length; i++) {
+            for (let j = i + 1; j < declaredPaths.length; j++) {
+                const a = declaredPaths[i];
+                const b = declaredPaths[j];
+                const relationship = (0, path_helpers_1.pathsOverlap)(a.path, b.path);
+                if (relationship === 'none')
+                    continue;
+                const sameArea = a.areaName === b.areaName;
+                violations.push({
+                    ruleId: sameArea ? 'auxiliary-area-paths-self-overlap' : 'auxiliary-area-paths-overlap',
+                    severity: 'error',
+                    file,
+                    path: sameArea
+                        ? `areas[${a.areaIndex}].paths`
+                        : undefined,
+                    message: sameArea
+                        ? `Area "${a.areaName}" declares overlapping paths "${a.path}" and "${b.path}"`
+                        : `Paths overlap between areas "${a.areaName}" ("${a.path}") and "${b.areaName}" ("${b.path}")`,
+                    impact: 'Two area declarations covering the same file make ownership ambiguous',
+                    suggestion: 'Make the paths disjoint. If one folder genuinely sits inside another area, drop the redundant entry.',
+                });
+            }
+        }
+        const errors = violations.filter((v) => v.severity === 'error');
+        return { valid: errors.length === 0, violations };
+    }
+}
+exports.AuxiliaryManifestValidator = AuxiliaryManifestValidator;
+//# sourceMappingURL=AuxiliaryManifestValidator.js.map

package/dist/auxiliary/AuxiliaryManifestValidator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AuxiliaryManifestValidator.js","sourceRoot":"","sources":["../../src/auxiliary/AuxiliaryManifestValidator.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG;;;AAIH,yDAAsD;AA4BtD,MAAM,qBAAqB,GAAG,0CAA0C,CAAC;AAEzE,MAAa,0BAA0B;IACrC,YAAoB,SAA4B;QAA5B,cAAS,GAAT,SAAS,CAAmB;IAAG,CAAC;IAEpD,KAAK,CAAC,QAAQ,CAAC,OAA2C;QACxD,MAAM,UAAU,GAAiC,EAAE,CAAC;QACpD,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC;QACvC,MAAM,IAAI,GAAG,OAAO,CAAC,YAAY,IAAI,qBAAqB,CAAC;QAE3D,IAAI,CAAC,QAAQ,EAAE;YACb,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;SACpC;QAED,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,IAAI,EAAE,CAAC;QAEnC,oBAAoB;QACpB,MAAM,SAAS,GAAG,IAAI,GAAG,EAAkB,CAAC;QAC5C,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE;YAC1B,MAAM,KAAK,GAAG,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAC5C,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;YACpC,IAAI,KAAK,KAAK,CAAC,EAAE;gBACf,UAAU,CAAC,IAAI,CAAC;oBACd,MAAM,EAAE,+BAA+B;oBACvC,QAAQ,EAAE,OAAO;oBACjB,IAAI;oBACJ,IAAI,EAAE,SAAS,GAAG,QAAQ;oBAC1B,OAAO,EAAE,cAAc,IAAI,CAAC,IAAI,8BAA8B;oBAC9D,MAAM,EAAE,+FAA+F;oBACvG,UAAU,EAAE,kEAAkE;iBAC/E,CAAC,CAAC;aACJ;QACH,CAAC,CAAC,CAAC;QAEH,4CAA4C;QAC5C,MAAM,aAAa,GAAoF,EAAE,CAAC;QAC1G,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,GAAG,KAAK,CAAC,MAAM,EAAE,OAAO,EAAE,EAAE;YACvD,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC;YAC5B,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC;YAC/B,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,GAAG,KAAK,CAAC,MAAM,EAAE,OAAO,EAAE,EAAE;gBACvD,MAAM,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC;gBACzB,aAAa,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC;gBAE7F,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC;gBAClD,IAAI,CAAC,CAAC,MAAM,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,EAAE;oBAC5C,UAAU,CAAC,IAAI,CAAC;wBACd,MAAM,EAAE,6BAA6B;wBACrC,QAAQ,EAAE,MAAM;wBAChB,IAAI;wBACJ,IAAI,EAAE,SAAS,OAAO,WAAW,OAAO,GAAG;wBAC3C,OAAO,EAAE,SAAS,CAAC,uBAAuB,IAAI,CAAC,IAAI,kBAAkB;wBACrE,MAAM,EAAE,uEAAuE;wBAC/E,UAAU,EAAE,iGAAiG;qBAC9G,CAAC,CAAC;iBACJ;aACF;SACF;QAED,uEAAuE;QACvE,wEAAwE;QACxE,8BAA8B;QAC9B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,aAAa,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE;YAC7C,KAAK,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,aAAa,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE;gBACjD,MAAM,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC;gBAC3B,MAAM,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC;gBAC3B,MAAM,YAAY,GAAG,IAAA,2BAAY,EAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;gBAClD,IAAI,YAAY,KAAK,MAAM;oBAAE,SAAS;gBAEtC,MAAM,QAAQ,GAAG,CAAC,CAAC,QAAQ,KAAK,CAAC,CAAC,QAAQ,CAAC;gBAC3C,UAAU,CAAC,IAAI,CAAC;oBACd,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC,mCAAmC,CAAC,CAAC,CAAC,8BAA8B;oBACvF,QAAQ,EAAE,OAAO;oBACjB,IAAI;oBACJ,IAAI,EAAE,QAAQ;wBACZ,CAAC,CAAC,SAAS,CAAC,CAAC,SAAS,SAAS;wBAC/B,CAAC,CAAC,SAAS;oBACb,OAAO,EAAE,QAAQ;wBACf,CAAC,CAAC,SAAS,CAAC,CAAC,QAAQ,iCAAiC,CAAC,CAAC,IAAI,UAAU,CAAC,CAAC,IAAI,GAAG;wBAC/E,CAAC,CAAC,gCAAgC,CAAC,CAAC,QAAQ,OAAO,CAAC,CAAC,IAAI,WAAW,CAAC,CAAC,QAAQ,OAAO,CAAC,CAAC,IAAI,IAAI;oBACjG,MAAM,EAAE,uEAAuE;oBAC/E,UAAU,EAAE,sGAAsG;iBACnH,CAAC,CAAC;aACJ;SACF;QAED,MAAM,MAAM,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC;QAChE,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,UAAU,EAAE,CAAC;IACpD,CAAC;CACF;AAtFD,gEAsFC"}

package/dist/auxiliary/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Auxiliary module
+ *
+ * Validation for `auxiliary.manifest.json` — the catalog of project regions
+ * that sit outside the OTEL telemetry surface (docs, .github, etc.).
+ */
+export { AuxiliaryManifestValidator, type AuxiliaryManifestValidationContext, type AuxiliaryManifestValidationResult, type AuxiliaryManifestViolation, } from './AuxiliaryManifestValidator';
+export { validateAreaScopeDisjoint, type ValidateAreaScopeDisjointInput, } from './validateAreaScopeDisjoint';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/auxiliary/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,0BAA0B,EAC1B,KAAK,kCAAkC,EACvC,KAAK,iCAAiC,EACtC,KAAK,0BAA0B,GAChC,MAAM,8BAA8B,CAAC;AAEtC,OAAO,EACL,yBAAyB,EACzB,KAAK,8BAA8B,GACpC,MAAM,6BAA6B,CAAC"}

package/dist/auxiliary/index.js

@@ -0,0 +1,14 @@
+"use strict";
+/**
+ * Auxiliary module
+ *
+ * Validation for `auxiliary.manifest.json` — the catalog of project regions
+ * that sit outside the OTEL telemetry surface (docs, .github, etc.).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateAreaScopeDisjoint = exports.AuxiliaryManifestValidator = void 0;
+var AuxiliaryManifestValidator_1 = require("./AuxiliaryManifestValidator");
+Object.defineProperty(exports, "AuxiliaryManifestValidator", { enumerable: true, get: function () { return AuxiliaryManifestValidator_1.AuxiliaryManifestValidator; } });
+var validateAreaScopeDisjoint_1 = require("./validateAreaScopeDisjoint");
+Object.defineProperty(exports, "validateAreaScopeDisjoint", { enumerable: true, get: function () { return validateAreaScopeDisjoint_1.validateAreaScopeDisjoint; } });
+//# sourceMappingURL=index.js.map

package/dist/auxiliary/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/auxiliary/index.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAEH,2EAKsC;AAJpC,wIAAA,0BAA0B,OAAA;AAM5B,yEAGqC;AAFnC,sIAAA,yBAAyB,OAAA"}

package/dist/auxiliary/validateAreaScopeDisjoint.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Area / Scope Disjointness Validator
+ *
+ * Cross-file check: project-area paths declared in
+ * `auxiliary.manifest.json` must be disjoint from every scope path declared
+ * in `architecture.scopes.canvas`. Areas and scopes carve up the repo into
+ * non-overlapping regions — any overlap (parent-child or otherwise) means a
+ * file is claimed by both an OTEL scope and an auxiliary area, which makes
+ * ownership ambiguous.
+ *
+ * Mirrors `validateScopeNamespaceNesting`'s cross-canvas pattern: takes both
+ * inputs, returns violations.
+ */
+import type { AuxiliaryManifest } from '../types/auxiliary';
+import type { ExtendedCanvas } from '../types/canvas';
+import type { AuxiliaryManifestViolation } from './AuxiliaryManifestValidator';
+export interface ValidateAreaScopeDisjointInput {
+    manifest: AuxiliaryManifest;
+    manifestPath?: string;
+    scopesCanvas?: ExtendedCanvas;
+    scopesCanvasPath?: string;
+}
+export declare function validateAreaScopeDisjoint(input: ValidateAreaScopeDisjointInput): AuxiliaryManifestViolation[];
+//# sourceMappingURL=validateAreaScopeDisjoint.d.ts.map

package/dist/auxiliary/validateAreaScopeDisjoint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validateAreaScopeDisjoint.d.ts","sourceRoot":"","sources":["../../src/auxiliary/validateAreaScopeDisjoint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAGtD,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,8BAA8B,CAAC;AAE/E,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,cAAc,CAAC;IAC9B,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAID,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,8BAA8B,GACpC,0BAA0B,EAAE,CAwC9B"}

package/dist/auxiliary/validateAreaScopeDisjoint.js

@@ -0,0 +1,61 @@
+"use strict";
+/**
+ * Area / Scope Disjointness Validator
+ *
+ * Cross-file check: project-area paths declared in
+ * `auxiliary.manifest.json` must be disjoint from every scope path declared
+ * in `architecture.scopes.canvas`. Areas and scopes carve up the repo into
+ * non-overlapping regions — any overlap (parent-child or otherwise) means a
+ * file is claimed by both an OTEL scope and an auxiliary area, which makes
+ * ownership ambiguous.
+ *
+ * Mirrors `validateScopeNamespaceNesting`'s cross-canvas pattern: takes both
+ * inputs, returns violations.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateAreaScopeDisjoint = void 0;
+const canvas_1 = require("../types/canvas");
+const path_helpers_1 = require("../events/path-helpers");
+const DEFAULT_MANIFEST_PATH = '.principal-views/auxiliary.manifest.json';
+function validateAreaScopeDisjoint(input) {
+    const { manifest, scopesCanvas } = input;
+    const manifestFile = input.manifestPath || DEFAULT_MANIFEST_PATH;
+    if (!scopesCanvas)
+        return [];
+    const scopePaths = [];
+    for (const node of scopesCanvas.nodes || []) {
+        if (!(0, canvas_1.isOtelScopeNode)(node))
+            continue;
+        const scope = node.otel?.scope;
+        const paths = node.paths;
+        if (!scope || !paths || paths.length === 0)
+            continue;
+        for (const p of paths)
+            scopePaths.push({ scope, path: p });
+    }
+    if (scopePaths.length === 0)
+        return [];
+    const violations = [];
+    const areas = manifest.areas || [];
+    areas.forEach((area, areaIdx) => {
+        (area.paths || []).forEach((areaPath, pathIdx) => {
+            for (const sp of scopePaths) {
+                const relationship = (0, path_helpers_1.pathsOverlap)(areaPath, sp.path);
+                if (relationship === 'none')
+                    continue;
+                violations.push({
+                    ruleId: 'auxiliary-area-scope-overlap',
+                    severity: 'error',
+                    file: manifestFile,
+                    path: `areas[${areaIdx}].paths[${pathIdx}]`,
+                    message: `Area "${area.name}" path "${areaPath}" overlaps scope "${sp.scope}" path "${sp.path}"`,
+                    impact: 'A file claimed by both an OTEL scope and an auxiliary area has ambiguous ownership — the manifest is meant to catalog regions outside the telemetry surface',
+                    suggestion: 'Make the area path disjoint from every scope path. If the folder is genuinely runtime code, drop it from the manifest; if it is auxiliary, narrow the scope path or move the folder.',
+                });
+            }
+        });
+    });
+    return violations;
+}
+exports.validateAreaScopeDisjoint = validateAreaScopeDisjoint;
+//# sourceMappingURL=validateAreaScopeDisjoint.js.map

package/dist/auxiliary/validateAreaScopeDisjoint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validateAreaScopeDisjoint.js","sourceRoot":"","sources":["../../src/auxiliary/validateAreaScopeDisjoint.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG;;;AAIH,4CAAkD;AAClD,yDAAsD;AAUtD,MAAM,qBAAqB,GAAG,0CAA0C,CAAC;AAEzE,SAAgB,yBAAyB,CACvC,KAAqC;IAErC,MAAM,EAAE,QAAQ,EAAE,YAAY,EAAE,GAAG,KAAK,CAAC;IACzC,MAAM,YAAY,GAAG,KAAK,CAAC,YAAY,IAAI,qBAAqB,CAAC;IAEjE,IAAI,CAAC,YAAY;QAAE,OAAO,EAAE,CAAC;IAE7B,MAAM,UAAU,GAA2C,EAAE,CAAC;IAC9D,KAAK,MAAM,IAAI,IAAI,YAAY,CAAC,KAAK,IAAI,EAAE,EAAE;QAC3C,IAAI,CAAC,IAAA,wBAAe,EAAC,IAAI,CAAC;YAAE,SAAS;QACrC,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC;QAC/B,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;QACzB,IAAI,CAAC,KAAK,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,SAAS;QACrD,KAAK,MAAM,CAAC,IAAI,KAAK;YAAE,UAAU,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC;KAC5D;IAED,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAEvC,MAAM,UAAU,GAAiC,EAAE,CAAC;IACpD,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,IAAI,EAAE,CAAC;IAEnC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE;QAC9B,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE;YAC/C,KAAK,MAAM,EAAE,IAAI,UAAU,EAAE;gBAC3B,MAAM,YAAY,GAAG,IAAA,2BAAY,EAAC,QAAQ,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC;gBACrD,IAAI,YAAY,KAAK,MAAM;oBAAE,SAAS;gBAEtC,UAAU,CAAC,IAAI,CAAC;oBACd,MAAM,EAAE,8BAA8B;oBACtC,QAAQ,EAAE,OAAO;oBACjB,IAAI,EAAE,YAAY;oBAClB,IAAI,EAAE,SAAS,OAAO,WAAW,OAAO,GAAG;oBAC3C,OAAO,EAAE,SAAS,IAAI,CAAC,IAAI,WAAW,QAAQ,qBAAqB,EAAE,CAAC,KAAK,WAAW,EAAE,CAAC,IAAI,GAAG;oBAChG,MAAM,EAAE,6JAA6J;oBACrK,UAAU,EAAE,sLAAsL;iBACnM,CAAC,CAAC;aACJ;QACH,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,OAAO,UAAU,CAAC;AACpB,CAAC;AA1CD,8DA0CC"}

package/dist/cli/codegen.d.ts

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+/**
+ * Code Generation CLI
+ *
+ * Generate types from canvas files.
+ *
+ * Usage:
+ *   npx @principal-ai/subsystems-core codegen my-flow.canvas
+ *   npx @principal-ai/subsystems-core codegen --lang typescript --output types/ my-flow.canvas
+ *
+ * Similar to:
+ *   - graphql-codegen (GraphQL)
+ *   - openapi-generator (OpenAPI)
+ *   - protoc (Protobuf)
+ */
+interface CliOptions {
+    language: 'typescript' | 'python' | 'go' | 'rust';
+    output?: string;
+    readonly?: boolean;
+    strictNullChecks?: boolean;
+    includeDocComments?: boolean;
+    namespace?: string;
+    watch?: boolean;
+}
+/**
+ * Parse command line arguments
+ */
+declare function parseArgs(args: string[]): {
+    options: CliOptions;
+    canvasFiles: string[];
+};
+/**
+ * Generate types for a canvas file
+ */
+declare function generateTypesForFile(canvasPath: string, options: CliOptions): string;
+/**
+ * Main entry point
+ */
+declare function main(): void;
+export { main, parseArgs, generateTypesForFile };
+//# sourceMappingURL=codegen.d.ts.map

package/dist/cli/codegen.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codegen.d.ts","sourceRoot":"","sources":["../../src/cli/codegen.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;GAaG;AAQH,UAAU,UAAU;IAClB,QAAQ,EAAE,YAAY,GAAG,QAAQ,GAAG,IAAI,GAAG,MAAM,CAAC;IAClD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;GAEG;AACH,iBAAS,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG;IAAE,OAAO,EAAE,UAAU,CAAC;IAAC,WAAW,EAAE,MAAM,EAAE,CAAA;CAAE,CAuDjF;AAED;;GAEG;AACH,iBAAS,oBAAoB,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,UA2DpE;AAkED;;GAEG;AACH,iBAAS,IAAI,SAuDZ;AAOD,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,oBAAoB,EAAE,CAAC"}