@knapsack/adapter-core 4.92.2--canary.eb7e898.0 → 4.92.2--canary.77d16bf.0

package/dist/entity-filename.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Source tagging — the single identity for a source on disk.
+ *
+ * A sourceTag is `{sourceEvt}-{hash}` — used as both the folder name
+ * and the filename tag for PCIF entities. Readable (you know the source type)
+ * and unique (hash of sourceKey).
+ *
+ * @example
+ *   sourceTag('KNAPSACK', { sourceKey: 'accutech@latest' })
+ *   // → 'knapsack-6d33514'
+ *
+ *   // Same tag everywhere:
+ *   //   sources/knapsack-6d33514/                              ← folder
+ *   //   sources/knapsack-6d33514/component/button.vue.knapsack-6d33514.mdx  ← filename
+ * */
+import { type SourceType } from './types.js';
+/**
+ * Compute the source tag — the readable, filesystem-safe, deterministic
+ * identity of a source. Used as folder name and filename tag.
+ */
+export declare function sourceTag(source: {
+    readonly sourceType: SourceType;
+    readonly sourceKey: string;
+}): string;
+/**
+ * Tag a bare filename for entity-stage naming.
+ * Inserts the sourceTag before the file extension.
+ */
+export declare function tagFilenameForEntity(filename: string, tag: ReturnType<typeof sourceTag>): string;
+//# sourceMappingURL=entity-filename.d.ts.map

package/dist/entity-filename.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-filename.d.ts","sourceRoot":"","sources":["../src/entity-filename.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;KAcK;AAGL,OAAO,EAAsB,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAEjE;;;GAGG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE;IAChC,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B,GAAG,MAAM,CAOT;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,UAAU,CAAC,OAAO,SAAS,CAAC,GAChC,MAAM,CAMR"}

package/dist/entity-filename.js

@@ -0,0 +1,42 @@
+/**
+ * Source tagging — the single identity for a source on disk.
+ *
+ * A sourceTag is `{sourceEvt}-{hash}` — used as both the folder name
+ * and the filename tag for PCIF entities. Readable (you know the source type)
+ * and unique (hash of sourceKey).
+ *
+ * @example
+ *   sourceTag('KNAPSACK', { sourceKey: 'accutech@latest' })
+ *   // → 'knapsack-6d33514'
+ *
+ *   // Same tag everywhere:
+ *   //   sources/knapsack-6d33514/                              ← folder
+ *   //   sources/knapsack-6d33514/component/button.vue.knapsack-6d33514.mdx  ← filename
+ * */
+import { createHash } from 'node:crypto';
+import { SOURCE_TYPE_TO_EVT } from './types.js';
+/**
+ * Compute the source tag — the readable, filesystem-safe, deterministic
+ * identity of a source. Used as folder name and filename tag.
+ */
+export function sourceTag(source) {
+    const evt = SOURCE_TYPE_TO_EVT[source.sourceType];
+    const hash = createHash('sha256')
+        .update(source.sourceKey)
+        .digest('hex')
+        .slice(0, 7);
+    return `${evt}-${hash}`;
+}
+/**
+ * Tag a bare filename for entity-stage naming.
+ * Inserts the sourceTag before the file extension.
+ */
+export function tagFilenameForEntity(filename, tag) {
+    const lastDot = filename.lastIndexOf('.');
+    if (lastDot === -1)
+        return `${filename}.${tag}`;
+    const base = filename.slice(0, lastDot);
+    const ext = filename.slice(lastDot + 1);
+    return `${base}.${tag}.${ext}`;
+}
+//# sourceMappingURL=entity-filename.js.map

package/dist/entity-filename.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-filename.js","sourceRoot":"","sources":["../src/entity-filename.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;KAcK;AAEL,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,kBAAkB,EAAmB,MAAM,YAAY,CAAC;AAEjE;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAC,MAGzB;IACC,MAAM,GAAG,GAAG,kBAAkB,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IAClD,MAAM,IAAI,GAAG,UAAU,CAAC,QAAQ,CAAC;SAC9B,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC;SACxB,MAAM,CAAC,KAAK,CAAC;SACb,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACf,OAAO,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC;AAC1B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAClC,QAAgB,EAChB,GAAiC;IAEjC,MAAM,OAAO,GAAG,QAAQ,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IAC1C,IAAI,OAAO,KAAK,CAAC,CAAC;QAAE,OAAO,GAAG,QAAQ,IAAI,GAAG,EAAE,CAAC;IAChD,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;IACxC,MAAM,GAAG,GAAG,QAAQ,CAAC,KAAK,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC;IACxC,OAAO,GAAG,IAAI,IAAI,GAAG,IAAI,GAAG,EAAE,CAAC;AACjC,CAAC"}

package/dist/entity-frontmatter.d.ts

@@ -0,0 +1,25 @@
+type BaseEntityFrontmatter = {
+    key: string;
+    sourceKey: string;
+    source: string;
+    lastIngested: string;
+    contentHash: string;
+    extraFields?: Record<string, unknown>;
+};
+export type ComponentEntityFrontmatter = BaseEntityFrontmatter & {
+    entityKind: 'COMPONENT';
+    platform: string;
+    import?: string | string[];
+};
+export type DocumentEntityFrontmatter = BaseEntityFrontmatter & {
+    entityKind: 'DOCUMENT';
+    platform?: string;
+};
+export type EntityFrontmatter = ComponentEntityFrontmatter | DocumentEntityFrontmatter;
+/**
+ * Shared PCIF frontmatter serializer for MDX entities at the sources/entities stages.
+ * Keeps common provenance consistent while still allowing component/document fields.
+ */
+export declare function buildEntityFrontmatter(frontmatter: EntityFrontmatter): string;
+export {};
+//# sourceMappingURL=entity-frontmatter.d.ts.map

package/dist/entity-frontmatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-frontmatter.d.ts","sourceRoot":"","sources":["../src/entity-frontmatter.ts"],"names":[],"mappings":"AAEA,KAAK,qBAAqB,GAAG;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvC,CAAC;AAEF,MAAM,MAAM,0BAA0B,GAAG,qBAAqB,GAAG;IAC/D,UAAU,EAAE,WAAW,CAAC;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;CAC5B,CAAC;AAEF,MAAM,MAAM,yBAAyB,GAAG,qBAAqB,GAAG;IAC9D,UAAU,EAAE,UAAU,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,iBAAiB,GACzB,0BAA0B,GAC1B,yBAAyB,CAAC;AAE9B;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,iBAAiB,GAAG,MAAM,CAuB7E"}

package/dist/entity-frontmatter.js

@@ -0,0 +1,25 @@
+import { stringify as stringifyYaml } from 'yaml';
+/**
+ * Shared PCIF frontmatter serializer for MDX entities at the sources/entities stages.
+ * Keeps common provenance consistent while still allowing component/document fields.
+ */
+export function buildEntityFrontmatter(frontmatter) {
+    const fields = {
+        key: frontmatter.key,
+        sourceKey: frontmatter.sourceKey,
+        source: frontmatter.source,
+    };
+    if (frontmatter.platform) {
+        fields.platform = frontmatter.platform;
+    }
+    if (frontmatter.entityKind === 'COMPONENT' && frontmatter.import) {
+        fields.import = frontmatter.import;
+    }
+    if (frontmatter.extraFields) {
+        Object.assign(fields, frontmatter.extraFields);
+    }
+    fields.lastIngested = frontmatter.lastIngested;
+    fields.contentHash = frontmatter.contentHash;
+    return `---\n${stringifyYaml(fields, { lineWidth: 0 }).trimEnd()}\n---`;
+}
+//# sourceMappingURL=entity-frontmatter.js.map

package/dist/entity-frontmatter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-frontmatter.js","sourceRoot":"","sources":["../src/entity-frontmatter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,IAAI,aAAa,EAAE,MAAM,MAAM,CAAC;AA0BlD;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CAAC,WAA8B;IACnE,MAAM,MAAM,GAA4B;QACtC,GAAG,EAAE,WAAW,CAAC,GAAG;QACpB,SAAS,EAAE,WAAW,CAAC,SAAS;QAChC,MAAM,EAAE,WAAW,CAAC,MAAM;KAC3B,CAAC;IAEF,IAAI,WAAW,CAAC,QAAQ,EAAE,CAAC;QACzB,MAAM,CAAC,QAAQ,GAAG,WAAW,CAAC,QAAQ,CAAC;IACzC,CAAC;IAED,IAAI,WAAW,CAAC,UAAU,KAAK,WAAW,IAAI,WAAW,CAAC,MAAM,EAAE,CAAC;QACjE,MAAM,CAAC,MAAM,GAAG,WAAW,CAAC,MAAM,CAAC;IACrC,CAAC;IAED,IAAI,WAAW,CAAC,WAAW,EAAE,CAAC;QAC5B,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,WAAW,CAAC,CAAC;IACjD,CAAC;IAED,MAAM,CAAC,YAAY,GAAG,WAAW,CAAC,YAAY,CAAC;IAC/C,MAAM,CAAC,WAAW,GAAG,WAAW,CAAC,WAAW,CAAC;IAE7C,OAAO,QAAQ,aAAa,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,OAAO,CAAC;AAC1E,CAAC"}

package/dist/entity-hash.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Compute a content hash for MDX entity bodies (first 12 hex chars of SHA-256).
+ * Used in frontmatter to track entity content changes across ingests.
+ */
+export declare function contentHash(content: string): string;
+//# sourceMappingURL=entity-hash.d.ts.map

package/dist/entity-hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-hash.d.ts","sourceRoot":"","sources":["../src/entity-hash.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAKnD"}

package/dist/entity-hash.js

@@ -0,0 +1,12 @@
+import { createHash } from 'node:crypto';
+/**
+ * Compute a content hash for MDX entity bodies (first 12 hex chars of SHA-256).
+ * Used in frontmatter to track entity content changes across ingests.
+ */
+export function contentHash(content) {
+    return createHash('sha256')
+        .update(content, 'utf-8')
+        .digest('hex')
+        .slice(0, 12);
+}
+//# sourceMappingURL=entity-hash.js.map

package/dist/entity-hash.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-hash.js","sourceRoot":"","sources":["../src/entity-hash.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,OAAe;IACzC,OAAO,UAAU,CAAC,QAAQ,CAAC;SACxB,MAAM,CAAC,OAAO,EAAE,OAAO,CAAC;SACxB,MAAM,CAAC,KAAK,CAAC;SACb,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAClB,CAAC"}

package/dist/index.d.ts

@@ -4,11 +4,15 @@
  * Core types, interfaces, and utilities for PCIF ingestion.
  * All ingestion pipelines depend on this package for shared infrastructure.
  */
-export type { SourceType, EntityKind, IngestSourceType, ContextEntity, Manifest, ManifestItem, ValidationResult, PipelineStage, StageInfo, MdxConfig, StorybookConfig, KnapsackConfig, FigmaConfig, ParserConfig, AdapterMessage, } from './types.js';
+export type { SourceType, EntityKind, IngestSourceType, ContextEntity, Manifest, ManifestItem, ValidationResult, PipelineStage, StageStatus, StageInfo, MdxConfig, StorybookConfig, KnapsackConfig, FigmaConfig, ParserConfig, ChannelConfig, AdapterMessage, } from './types.js';
 export { SOURCE_TYPE_TO_EVT } from './types.js';
 export type { Validator, Parser, Transformer, Analyzer, ContextSrcAdapter, } from './interface.js';
 export type { RuntimeDeps } from './runtime-deps.js';
 export type { Logger, IngestEvt, LogContext } from './log.js';
 export { buildLogContext } from './log.js';
 export { writeFile } from './fs.js';
+export { sourceTag, tagFilenameForEntity } from './entity-filename.js';
+export { contentHash } from './entity-hash.js';
+export type { ComponentEntityFrontmatter, DocumentEntityFrontmatter, EntityFrontmatter, } from './entity-frontmatter.js';
+export { buildEntityFrontmatter } from './entity-frontmatter.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,YAAY,EAEV,UAAU,EACV,UAAU,EACV,gBAAgB,EAEhB,aAAa,EAEb,QAAQ,EACR,YAAY,EACZ,gBAAgB,EAEhB,aAAa,EACb,SAAS,EAET,SAAS,EACT,eAAe,EACf,cAAc,EACd,WAAW,EACX,YAAY,EAEZ,cAAc,GACf,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAGhD,YAAY,EACV,SAAS,EACT,MAAM,EACN,WAAW,EACX,QAAQ,EACR,iBAAiB,GAClB,MAAM,gBAAgB,CAAC;AAGxB,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGrD,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAC9D,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAG3C,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,YAAY,EAEV,UAAU,EACV,UAAU,EACV,gBAAgB,EAEhB,aAAa,EAEb,QAAQ,EACR,YAAY,EACZ,gBAAgB,EAEhB,aAAa,EACb,WAAW,EACX,SAAS,EAET,SAAS,EACT,eAAe,EACf,cAAc,EACd,WAAW,EACX,YAAY,EAEZ,aAAa,EAEb,cAAc,GACf,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAGhD,YAAY,EACV,SAAS,EACT,MAAM,EACN,WAAW,EACX,QAAQ,EACR,iBAAiB,GAClB,MAAM,gBAAgB,CAAC;AAGxB,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGrD,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAC9D,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAG3C,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAGpC,OAAO,EAAE,SAAS,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAGvE,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAG/C,YAAY,EACV,0BAA0B,EAC1B,yBAAyB,EACzB,iBAAiB,GAClB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/index.js

@@ -8,4 +8,9 @@ export { SOURCE_TYPE_TO_EVT } from './types.js';
 export { buildLogContext } from './log.js';
 // Filesystem utilities
 export { writeFile } from './fs.js';
+// Entity filename utilities (PCIF entities/ stage naming)
+export { sourceTag, tagFilenameForEntity } from './entity-filename.js';
+// Entity content hashing
+export { contentHash } from './entity-hash.js';
+export { buildEntityFrontmatter } from './entity-frontmatter.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA0BH,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAgBhD,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAE3C,uBAAuB;AACvB,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA6BH,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAgBhD,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAE3C,uBAAuB;AACvB,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEpC,0DAA0D;AAC1D,OAAO,EAAE,SAAS,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAEvE,yBAAyB;AACzB,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAQ/C,OAAO,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/types.d.ts

@@ -37,23 +37,44 @@ export interface ContextEntity {
     sourceKey: string;
 }
 /**
- * Pipeline stages — the ordered lifecycle stages an adapter runs through
+ * Pipeline stages — the ordered lifecycle stages an adapter runs through.
+ *
+ * Source operator (slurp): validate → parse → transform
+ * Distro operator (distro): mount → detect → build
  */
-export type PipelineStage = 'parse' | 'transform' | 'validate';
+export type PipelineStage = 'validate' | 'parse' | 'transform' | 'mount' | 'detect' | 'build';
 /**
- * Metadata recorded when a stage completes
+ * Stage result status — follows dbt/OTel conventions.
+ *
+ * - success: completed normally, produced expected output
+ * - failure: completed but result is bad (data problem, retry won't help)
+ * - error:   didn't complete (infra/code problem, retry may help)
+ * - skipped: didn't run (precondition not met, intentionally bypassed)
+ */
+export type StageStatus = 'success' | 'failure' | 'error' | 'skipped';
+/**
+ * Metadata recorded when a stage completes.
+ *
+ * Modeled after dbt run_results.json per-node shape:
+ * every stage produces a uniform result with status, timing, and counts.
  */
 export interface StageInfo {
+    /** Outcome of this stage */
+    status: StageStatus;
     /** Number of items processed in this stage */
     itemCount: number;
     /** Number of errors in this stage */
     errors: number;
     /** Duration of this stage in milliseconds */
     durationMs: number;
+    /** ISO-8601 timestamp when this stage started */
+    startedAt: string;
     /** ISO-8601 timestamp when this stage completed */
     completedAt: string;
-    /** Number of items discovered in source (parse stage only) */
+    /** Number of items discovered (parse stage: total before filtering) */
     discoveredItemCount?: number;
+    /** Human-readable message (error detail, skip reason, summary) */
+    message?: string;
 }
 /**
  * A single item in the manifest
@@ -142,17 +163,25 @@ export interface StorybookConfig {
     limit?: number;
 }
 /**
- * TBD: Knapsack parser configuration
+ * Knapsack adapter configuration
+ *
+ * The adapter reads a pre-staged appClientData.json from Storage.
+ * Auth is handled by the GraphQL API before the adapter runs —
+ * the adapter never authenticates.
+ *
+ * @see libs/ingest-pipeline/adapters/knapsack/docs/SPEC.md
  */
 export interface KnapsackConfig {
-    /** Stable identifier for this source */
+    /** Derived sourceKey (e.g. 'toby@latest'). Set by controller via adapter.sourceKey(). */
     sourceKey: string;
-    /** Branch name */
+    /** Site identifier — always scoped to a single Knapsack site */
+    siteId: string;
+    /** Branch name ('latest' for production, or branch name for drafts) */
     branchName: string;
-    /** Input path to raw sitemeta schema.json */
+    /** Path to pre-staged appClientData.json in Storage */
     inputPath: string;
-    /** Optional explicit site ID (defaults to auto-detection from filename) */
-    siteId?: string;
+    /** Commit SHA of the staged blob (short hex, e.g. 'bcf262f'). Provenance metadata — not part of sourceKey. */
+    contentHash?: string;
 }
 /**
  * TBD: Figma parser configuration
@@ -180,48 +209,61 @@ export type ParserConfig = ({
     type: 'figma';
 } & FigmaConfig);
 /**
- * Structured messages the parser sends to the application layer.
+ * Configuration for the distro operator (mount + detect + build).
+ * channelKey is derived from channel.name in DB — url-safe, durable.
+ */
+export interface ChannelConfig {
+    /** Channel key — url-safe slug, folder name, durable id */
+    readonly channelKey: string;
+    /** Site identifier */
+    readonly siteId: string;
+}
+/**
+ * Structured messages emitted by operators and the controller.
  * The handler wires these to SQS, webhooks, or direct callbacks.
- * These are all TBD, we need to define them later.
- * TODO: needs input from what the ui and db WANT from parsers
+ *
+ * Universal event model inspired by dbt run_results and OTel CICD conventions:
+ * - stage.started:  stage announces scope of work
+ * - item.ok:        per-item success with domain-specific metadata
+ * - item.error:     per-item failure
+ * - item.skip:      per-item intentional bypass
+ * - stage.complete: stage finished with aggregate StageInfo + status
  */
 export type AdapterMessage = {
-    stage: 'parse';
-    type: 'progress';
-    itemsComplete: number;
-    itemsTotal: number;
-} | {
-    stage: 'parse';
-    type: 'item.extracted';
-    ref: string;
-} | {
-    stage: 'parse';
-    type: 'item.failed';
-    ref: string;
-    error: string;
+    stage: PipelineStage;
+    type: 'stage.started';
+    /** Source identity — set by source stages (parse, transform) */
+    sourceKey?: string;
+    /** Channel identity — set by distro stages (mount, detect, build) */
+    channelKey?: string;
 } | {
-    stage: 'transform';
-    type: 'progress';
-    itemsComplete: number;
-    itemsTotal: number;
+    stage: PipelineStage;
+    type: 'stage.complete';
+    stageInfo: StageInfo;
+    /** Source identity — set by source stages (parse, transform) */
+    sourceKey?: string;
+    /** Channel identity — set by distro stages (mount, detect, build) */
+    channelKey?: string;
 } | {
-    stage: 'transform';
-    type: 'item.extracted';
+    stage: PipelineStage;
+    type: 'item.ok';
+    /** Item identity — ref for source stages, canonical key for distro stages */
     ref: string;
+    /** Domain-specific metadata (entityCounts, conflictCount, files, etc.) */
+    metadata?: Record<string, unknown>;
 } | {
-    stage: 'transform';
-    type: 'item.failed';
+    stage: PipelineStage;
+    type: 'item.error';
     ref: string;
     error: string;
+    /** Domain-specific context about the failure */
+    metadata?: Record<string, unknown>;
 } | {
-    stage: 'parse';
-    type: 'stage.complete';
-    stageInfo: StageInfo;
-    sourceKey: string;
-} | {
-    stage: 'transform';
-    type: 'stage.complete';
-    stageInfo: StageInfo;
-    sourceKey: string;
+    stage: PipelineStage;
+    type: 'item.skip';
+    ref: string;
+    reason: string;
+    /** Domain-specific context about what was skipped */
+    metadata?: Record<string, unknown>;
 };
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@knapsack/adapter-core",
   "description": "Core types, interfaces, and logging for ContextSrcAdapters",
-  "version": "4.92.2--canary.eb7e898.0",
+  "version": "4.92.2--canary.77d16bf.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -22,14 +22,15 @@
   },
   "author": "Knapsack (https://www.knapsack.cloud)",
   "dependencies": {
-    "@knapsack/logger": "4.92.2--canary.eb7e898.0"
+    "@knapsack/logger": "4.92.2--canary.77d16bf.0",
+    "yaml": "^2.7.0"
   },
   "devDependencies": {
-    "@knapsack/eslint-config-starter": "4.92.2--canary.eb7e898.0",
-    "@knapsack/typescript-config-starter": "4.92.2--canary.eb7e898.0",
+    "@knapsack/eslint-config-starter": "4.92.2--canary.77d16bf.0",
+    "@knapsack/typescript-config-starter": "4.92.2--canary.77d16bf.0",
     "@types/node": "^22.19.11",
     "eslint": "^9.20.0",
-    "typescript": "^6.0.0"
+    "typescript": "^5.9.3"
   },
   "license": "GPL-2.0-or-later",
   "publishConfig": {
@@ -40,5 +41,5 @@
     "directory": "libs/ingest-pipeline/adapters/core",
     "type": "git"
   },
-  "gitHead": "eb7e898467cd0ff7b1e27faa3cffc69ccd985720"
+  "gitHead": "77d16bf68c911461c261b5247b563a73e9c1eae6"
 }

package/tsconfig.json

@@ -1,6 +1,5 @@
 {
   "compilerOptions": {
-    "types": ["node"],
     "target": "ES2022",
     "module": "NodeNext",
     "moduleResolution": "NodeNext",
@@ -16,5 +15,5 @@
     "sourceMap": true
   },
   "include": ["src/**/*"],
-  "exclude": ["node_modules", "dist"]
+  "exclude": ["node_modules", "dist", "src/**/*.test.ts"]
 }