@lobu/connector-sdk 7.2.0 → 9.0.0

package/dist/index.js

@@ -8,8 +8,14 @@ export { ConnectorRuntime } from './connector-runtime.js';
 export { IDENTITY } from './connector-types.js';
 // Identity-engine SDK contracts. Each schema export is both a TypeBox
 // runtime validator (value) AND a TypeScript type via declaration merging.
-export { AssuranceLevel, assuranceMeets, AutoCreateWhenRule, CLAIM_COLLISION_SEMANTIC_TYPE, ClaimCollisionPayload, ConnectorFact, ConnectorIdentityCapability, DerivedFromProvenance, DerivedRelationshipMetadata, FactEventMetadata, IDENTITY_FACT_SEMANTIC_TYPE, MatchStrategy, RelationshipTypeIdentityMetadata, } from './identity-types.js';
-export { isSourceNativeEventType, SOURCE_NATIVE_EVENT_TYPES } from './event-taxonomy.js';
+// We import then re-export locally instead of `export { … } from
+// './identity-types.js'`: bun's ESM linker (macOS + node26 + bun 1.3.5)
+// intermittently fails to resolve a name through a large transitive
+// re-export barrel, surfacing as a flaky `Export named 'X' not found in
+// dist/index.js` under concurrent test load (issue #976). A local export
+// list links against the already-bound import.
+import { AssuranceLevel, assuranceMeets, AutoCreateWhenRule, CLAIM_COLLISION_SEMANTIC_TYPE, ClaimCollisionPayload, ConnectorFact, ConnectorIdentityCapability, DerivedFromProvenance, DerivedRelationshipMetadata, FactEventMetadata, IDENTITY_FACT_SEMANTIC_TYPE, RelationshipTypeIdentityMetadata, } from './identity-types.js';
+export { AssuranceLevel, assuranceMeets, AutoCreateWhenRule, CLAIM_COLLISION_SEMANTIC_TYPE, ClaimCollisionPayload, ConnectorFact, ConnectorIdentityCapability, DerivedFromProvenance, DerivedRelationshipMetadata, FactEventMetadata, IDENTITY_FACT_SEMANTIC_TYPE, RelationshipTypeIdentityMetadata, };
 export { normalizeAuthUserId, normalizeEmail, normalizeGithubLogin, normalizeGithubRepoFullName, normalizeGoogleContactId, normalizeNumericId, normalizeIdentifier, normalizePhone, normalizeSlackUserId, normalizeWaJid, } from './identity-normalize.js';
 // Logger
 export { sdkLogger, sdkLogger as logger } from './logger.js';
@@ -19,9 +25,12 @@ export { withHttpRetry } from './retry.js';
 export { calculateEngagementScore } from './scoring.js';
 export { addWatcherPeriod, alignToWatcherWindowStart, getAvailableWatcherGranularities, getFinerWatcherGranularities, getNextWatcherGranularity, getWatcherDateTruncUnit, inferWatcherGranularityFromDays, inferWatcherGranularityFromSchedule, isWatcherTimeGranularity, shiftWatcherPeriod, subtractWatcherPeriod, WATCHER_TIME_GRANULARITIES, } from './watcher-time.js';
 export { acquireBrowser, BrowserAuthCascadeError } from './browser/acquire.js';
-export { discoverChromeListeningPorts, discoverChromeProcessCdpUrls, fetchCdpVersionInfo, normalizeCdpUrl, resolveCdpUrl, tryWebSocketCdp, } from './browser/cdp.js';
+export { fetchCdpVersionInfo, resolveCdpUrl, } from './browser/cdp.js';
 export { CdpPage } from './browser/cdp-page.js';
-export { captureErrorArtifacts, launchBrowser, withErrorCapture, } from './browser/launcher.js';
-export { getRandomDelay, humanWait, launchStealthBrowser, randomScroll, testBotDetection, } from './browser/stealth.js';
+export { captureErrorArtifacts, launchBrowser, } from './browser/launcher.js';
 export { browserNetworkSync } from './browser-network.js';
+export { fileSystemSourceFromUri } from './file-source.js';
+export { GitFileSource, parseGitUri } from './sources/git-file-source.js';
+export { TarballFileSource } from './sources/tarball-file-source.js';
+export { LocalFileSource } from './sources/local-file-source.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,gFAAgF;AAChF,0CAA0C;AAC1C,gFAAgF;AAIhF,OAAO,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAGzC,OAAO,EAAE,OAAO,IAAI,EAAE,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AAC9C,0CAA0C;AAC1C,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAsC1D,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAChD,sEAAsE;AACtE,2EAA2E;AAC3E,OAAO,EACL,cAAc,EACd,cAAc,EACd,kBAAkB,EAClB,6BAA6B,EAC7B,qBAAqB,EACrB,aAAa,EACb,2BAA2B,EAC3B,qBAAqB,EACrB,2BAA2B,EAC3B,iBAAiB,EACjB,2BAA2B,EAC3B,aAAa,EACb,gCAAgC,GACjC,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,uBAAuB,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AACzF,OAAO,EACL,mBAAmB,EACnB,cAAc,EACd,oBAAoB,EACpB,2BAA2B,EAC3B,wBAAwB,EACxB,kBAAkB,EAClB,mBAAmB,EACnB,cAAc,EACd,oBAAoB,EACpB,cAAc,GACf,MAAM,yBAAyB,CAAC;AACjC,SAAS;AACT,OAAO,EAAE,SAAS,EAAE,SAAS,IAAI,MAAM,EAAE,MAAM,aAAa,CAAC;AAC7D,QAAQ;AACR,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC3C,UAAU;AACV,OAAO,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AAExD,OAAO,EACL,gBAAgB,EAChB,yBAAyB,EACzB,gCAAgC,EAChC,4BAA4B,EAC5B,yBAAyB,EACzB,uBAAuB,EACvB,+BAA+B,EAC/B,mCAAmC,EACnC,wBAAwB,EACxB,kBAAkB,EAClB,qBAAqB,EACrB,0BAA0B,GAC3B,MAAM,mBAAmB,CAAC;AAO3B,OAAO,EAAE,cAAc,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAE/E,OAAO,EACL,4BAA4B,EAC5B,4BAA4B,EAC5B,mBAAmB,EACnB,eAAe,EACf,aAAa,EACb,eAAe,GAChB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAEhD,OAAO,EACL,qBAAqB,EACrB,aAAa,EACb,gBAAgB,GACjB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACL,cAAc,EACd,SAAS,EACT,oBAAoB,EACpB,YAAY,EACZ,gBAAgB,GACjB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,0CAA0C;AAC1C,gFAAgF;AAIhF,OAAO,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAGzC,OAAO,EAAE,OAAO,IAAI,EAAE,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AAC9C,0CAA0C;AAC1C,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAqC1D,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAChD,sEAAsE;AACtE,2EAA2E;AAC3E,iEAAiE;AACjE,wEAAwE;AACxE,oEAAoE;AACpE,wEAAwE;AACxE,yEAAyE;AACzE,+CAA+C;AAC/C,OAAO,EACL,cAAc,EACd,cAAc,EACd,kBAAkB,EAClB,6BAA6B,EAC7B,qBAAqB,EACrB,aAAa,EACb,2BAA2B,EAC3B,qBAAqB,EACrB,2BAA2B,EAC3B,iBAAiB,EACjB,2BAA2B,EAC3B,gCAAgC,GACjC,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,cAAc,EACd,cAAc,EACd,kBAAkB,EAClB,6BAA6B,EAC7B,qBAAqB,EACrB,aAAa,EACb,2BAA2B,EAC3B,qBAAqB,EACrB,2BAA2B,EAC3B,iBAAiB,EACjB,2BAA2B,EAC3B,gCAAgC,GACjC,CAAC;AACF,OAAO,EACL,mBAAmB,EACnB,cAAc,EACd,oBAAoB,EACpB,2BAA2B,EAC3B,wBAAwB,EACxB,kBAAkB,EAClB,mBAAmB,EACnB,cAAc,EACd,oBAAoB,EACpB,cAAc,GACf,MAAM,yBAAyB,CAAC;AACjC,SAAS;AACT,OAAO,EAAE,SAAS,EAAE,SAAS,IAAI,MAAM,EAAE,MAAM,aAAa,CAAC;AAC7D,QAAQ;AACR,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC3C,UAAU;AACV,OAAO,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AAExD,OAAO,EACL,gBAAgB,EAChB,yBAAyB,EACzB,gCAAgC,EAChC,4BAA4B,EAC5B,yBAAyB,EACzB,uBAAuB,EACvB,+BAA+B,EAC/B,mCAAmC,EACnC,wBAAwB,EACxB,kBAAkB,EAClB,qBAAqB,EACrB,0BAA0B,GAC3B,MAAM,mBAAmB,CAAC;AAO3B,OAAO,EAAE,cAAc,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAE/E,OAAO,EACL,mBAAmB,EACnB,aAAa,GACd,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAEhD,OAAO,EACL,qBAAqB,EACrB,aAAa,GACd,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAmB1D,OAAO,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAE1E,OAAO,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AACrE,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC"}

package/dist/reaction-client-types.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Type declarations for watcher reaction scripts.
+ *
+ * Reaction scripts run inside an isolated-vm sandbox where `client` is a
+ * Proxy that dispatches calls to the host. You can't import real packages
+ * at runtime, but you CAN use these types for editor autocompletion.
+ *
+ * Usage:
+ *   import type { ReactionClient, ReactionContext } from "@lobu/connector-sdk";
+ *
+ *   export default async (ctx: ReactionContext, client: ReactionClient) => {
+ *     await client.knowledge.save({ content: "...", semantic_type: "digest" });
+ *   };
+ */
+import type { ReactionContext } from "./reaction-sdk.js";
+export type { ReactionContext };
+export interface KnowledgeSearchInput {
+    query?: string;
+    entity_type?: string;
+    entity_id?: number;
+    fuzzy?: boolean;
+    min_similarity?: number;
+    limit?: number;
+}
+export interface KnowledgeSaveInput {
+    entity_ids?: number[];
+    content: string;
+    semantic_type: string;
+    metadata?: Record<string, unknown>;
+    title?: string;
+    slug?: string;
+}
+export interface KnowledgeReadInput {
+    content_id?: number;
+    watcher_id?: number;
+    since?: string;
+    until?: string;
+    limit?: number;
+    entity_ids?: number[];
+}
+export interface EntityCreateInput {
+    type: string;
+    name: string;
+    slug?: string;
+    content?: string;
+    parent_id?: number;
+    metadata?: Record<string, unknown>;
+}
+export interface EntityUpdateInput {
+    entity_id: number;
+    name?: string;
+    slug?: string;
+    content?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface EntityLinkInput {
+    from_entity_id: number;
+    to_entity_id: number;
+    relationship_type_slug: string;
+    metadata?: Record<string, unknown>;
+}
+export interface EntityListFilter {
+    entity_type?: string;
+    search?: string;
+    limit?: number;
+    offset?: number;
+    sort_by?: string;
+    sort_order?: "asc" | "desc";
+}
+/**
+ * The client object available in reaction scripts.
+ *
+ * `client.knowledge`  — read/write/search knowledge events
+ * `client.entities`   — CRUD entities and relationships
+ * `client.query`      — raw SQL (results as JSON rows)
+ * `client.log`        — structured logging (appears in watcher run logs)
+ */
+export interface ReactionClient {
+    knowledge: {
+        search(input: KnowledgeSearchInput): Promise<unknown>;
+        save(input: KnowledgeSaveInput): Promise<unknown>;
+        read(input: KnowledgeReadInput): Promise<unknown>;
+        delete(input: number | {
+            event_id?: number;
+            event_ids?: number[];
+            reason?: string;
+        }): Promise<unknown>;
+    };
+    entities: {
+        list(filter?: EntityListFilter): Promise<unknown>;
+        get(entity_id: number): Promise<unknown>;
+        create(input: EntityCreateInput): Promise<{
+            id: number;
+        }>;
+        update(input: EntityUpdateInput): Promise<unknown>;
+        delete(entity_id: number, options?: {
+            force_delete_tree?: boolean;
+        }): Promise<unknown>;
+        link(input: EntityLinkInput): Promise<unknown>;
+        unlink(input: {
+            from_entity_id: number;
+            to_entity_id: number;
+            relationship_type_slug: string;
+        }): Promise<unknown>;
+        updateLink(input: {
+            from_entity_id: number;
+            to_entity_id: number;
+            relationship_type_slug: string;
+            metadata?: Record<string, unknown>;
+        }): Promise<unknown>;
+        listLinks(input: {
+            entity_id: number;
+            relationship_type_slug?: string;
+            limit?: number;
+            offset?: number;
+        }): Promise<unknown>;
+        search(query: string, options?: {
+            limit?: number;
+        }): Promise<unknown>;
+    };
+    /** Run a read-only SQL query against the org's Postgres. */
+    query(sql: string): Promise<unknown[]>;
+    /** Structured log — appears in the watcher run output. */
+    log(message: string, data?: Record<string, unknown>): void;
+}
+//# sourceMappingURL=reaction-client-types.d.ts.map

package/dist/reaction-client-types.d.ts.map

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

package/dist/reaction-client-types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=reaction-client-types.js.map

package/dist/reaction-client-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reaction-client-types.js","sourceRoot":"","sources":["../src/reaction-client-types.ts"],"names":[],"mappings":""}

package/dist/sources/cache.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Cache-layout helpers shared by all FileSystemSource implementations.
+ *
+ *   ${WORKSPACE_DIR}/.lobu-cache/sources/<sha256(uri)[:32]>/
+ *     ├── snapshot/        ← actual files (connector-visible via Snapshot.readFile)
+ *     ├── manifest.json    ← { ref, files: [{ path, sha256 }], fetched_at }
+ *     └── meta.json        ← { uri, kind }
+ *
+ *  - `WORKSPACE_DIR` env var is the cache root; falls back to `process.cwd()`.
+ *  - URI is hashed (sha256, first 32 hex chars = 128 bits) for filesystem-safe
+ *    naming. 128 bits is collision-resistant even against adversarial URIs
+ *    (1e19 URIs before 50% collision odds).
+ *  - One cache directory per URI — same URI yields the same directory across
+ *    runs so re-fetch is incremental for git, manifest-comparable for the rest.
+ *    On reuse, `meta.json`'s `uri` field is verified to match — a mismatch
+ *    (theoretical hash collision OR cache-root reuse across schemes) throws.
+ *  - The cache layout is intentionally NOT exported on the public API; this
+ *    module is internal to the SDK.
+ */
+export type SourceKind = 'git' | 'tarball' | 'local';
+export interface ManifestEntry {
+    path: string;
+    sha256: string;
+}
+export interface Manifest {
+    ref: string;
+    files: ManifestEntry[];
+    fetched_at: string;
+}
+export interface CacheMeta {
+    uri: string;
+    kind: SourceKind;
+}
+export interface CachePaths {
+    /** Absolute cache root for this URI. */
+    readonly root: string;
+    /** Where the source's files live (rootDir of the Snapshot). */
+    readonly snapshotDir: string;
+    /** manifest.json path. */
+    readonly manifestPath: string;
+    /** meta.json path. */
+    readonly metaPath: string;
+}
+/** Build the cache paths for `uri`, anchored under `cacheRoot`. */
+export declare function cachePathsFor(uri: string, cacheRoot?: string): CachePaths;
+/**
+ * Read `meta.json` if present and assert it matches `uri`. Throws on URI
+ * mismatch (defends against an adversarial collision OR an operator copying
+ * a cache dir across sources). Returns `null` for a fresh cache.
+ */
+export declare function readAndVerifyMeta(metaPath: string, expectedUri: string): Promise<CacheMeta | null>;
+/**
+ * Like `readAndVerifyMeta`, but rejects when the cache is uninitialised.
+ * Use this from `diffSinceRef()` paths — calling diff before fetch is a
+ * caller bug, and a missing meta also means a stale/collided cache dir
+ * should not be silently consumed.
+ */
+export declare function requireMeta(metaPath: string, expectedUri: string): Promise<CacheMeta>;
+export declare function withSourceLock<T>(uri: string, fn: () => Promise<T>): Promise<T>;
+/** Default cache root: `WORKSPACE_DIR` env, else `process.cwd()`. */
+export declare function defaultCacheRoot(): string;
+export declare function readManifest(path: string): Promise<Manifest | null>;
+export declare function writeManifest(path: string, manifest: Manifest): Promise<void>;
+export declare function readMeta(path: string): Promise<CacheMeta | null>;
+export declare function writeMeta(path: string, meta: CacheMeta): Promise<void>;
+/**
+ * Diff two manifests by `(path, sha256)`. Order-independent.
+ */
+export declare function diffManifests(prev: Manifest, next: Manifest): {
+    added: string[];
+    modified: string[];
+    removed: string[];
+};
+/**
+ * Canonicalize a manifest's `ref` from its file list:
+ *
+ *  sha256 over lines of `<path>\0<sha256>\n`, sorted by path.
+ *
+ * Deterministic across runs and platforms.
+ */
+export declare function canonicalManifestRef(files: ManifestEntry[]): string;
+//# sourceMappingURL=cache.d.ts.map

package/dist/sources/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/sources/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAMH,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,SAAS,GAAG,OAAO,CAAC;AAErD,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,QAAQ;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,SAAS;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,UAAU,CAAC;CAClB;AAED,MAAM,WAAW,UAAU;IACzB,wCAAwC;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,+DAA+D;IAC/D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,0BAA0B;IAC1B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,sBAAsB;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,mEAAmE;AACnE,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,GAAE,MAA2B,GAAG,UAAU,CAS7F;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAU3B;AAED;;;;;GAKG;AACH,wBAAsB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAQ3F;AAuBD,wBAAsB,cAAc,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAYrF;AAED,qEAAqE;AACrE,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AAED,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAQzE;AAED,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAEnF;AAED,wBAAsB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAQtE;AAED,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAE5E;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,QAAQ,EACd,IAAI,EAAE,QAAQ,GACb;IAAE,KAAK,EAAE,MAAM,EAAE,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAiB5D;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,aAAa,EAAE,GAAG,MAAM,CAUnE"}

package/dist/sources/cache.js

@@ -0,0 +1,169 @@
+/**
+ * Cache-layout helpers shared by all FileSystemSource implementations.
+ *
+ *   ${WORKSPACE_DIR}/.lobu-cache/sources/<sha256(uri)[:32]>/
+ *     ├── snapshot/        ← actual files (connector-visible via Snapshot.readFile)
+ *     ├── manifest.json    ← { ref, files: [{ path, sha256 }], fetched_at }
+ *     └── meta.json        ← { uri, kind }
+ *
+ *  - `WORKSPACE_DIR` env var is the cache root; falls back to `process.cwd()`.
+ *  - URI is hashed (sha256, first 32 hex chars = 128 bits) for filesystem-safe
+ *    naming. 128 bits is collision-resistant even against adversarial URIs
+ *    (1e19 URIs before 50% collision odds).
+ *  - One cache directory per URI — same URI yields the same directory across
+ *    runs so re-fetch is incremental for git, manifest-comparable for the rest.
+ *    On reuse, `meta.json`'s `uri` field is verified to match — a mismatch
+ *    (theoretical hash collision OR cache-root reuse across schemes) throws.
+ *  - The cache layout is intentionally NOT exported on the public API; this
+ *    module is internal to the SDK.
+ */
+import { createHash } from 'node:crypto';
+import { readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+/** Build the cache paths for `uri`, anchored under `cacheRoot`. */
+export function cachePathsFor(uri, cacheRoot = defaultCacheRoot()) {
+    const hash = createHash('sha256').update(uri).digest('hex').slice(0, 32);
+    const root = join(cacheRoot, '.lobu-cache', 'sources', hash);
+    return {
+        root,
+        snapshotDir: join(root, 'snapshot'),
+        manifestPath: join(root, 'manifest.json'),
+        metaPath: join(root, 'meta.json'),
+    };
+}
+/**
+ * Read `meta.json` if present and assert it matches `uri`. Throws on URI
+ * mismatch (defends against an adversarial collision OR an operator copying
+ * a cache dir across sources). Returns `null` for a fresh cache.
+ */
+export async function readAndVerifyMeta(metaPath, expectedUri) {
+    const meta = await readMeta(metaPath);
+    if (!meta)
+        return null;
+    if (meta.uri !== expectedUri) {
+        throw new Error(`FileSystemSource cache mismatch: ${metaPath} belongs to ${meta.uri}, ` +
+            `but ${expectedUri} was requested. Refusing to reuse cache directory.`);
+    }
+    return meta;
+}
+/**
+ * Like `readAndVerifyMeta`, but rejects when the cache is uninitialised.
+ * Use this from `diffSinceRef()` paths — calling diff before fetch is a
+ * caller bug, and a missing meta also means a stale/collided cache dir
+ * should not be silently consumed.
+ */
+export async function requireMeta(metaPath, expectedUri) {
+    const meta = await readAndVerifyMeta(metaPath, expectedUri);
+    if (!meta) {
+        throw new Error(`FileSystemSource: source not fetched yet — call fetch() before diffSinceRef() (${expectedUri})`);
+    }
+    return meta;
+}
+/**
+ * Per-source mutex. Same URI → shared `Promise` chain so concurrent
+ * `fetch()` calls serialize. Process-local only — fine for the embedded
+ * worker model where one worker subprocess owns its cache.
+ *
+ * v1 limitation: two processes sharing the same
+ * `${WORKSPACE_DIR}/.lobu-cache` are NOT coordinated by this lock —
+ * each gets its own in-memory `_sourceLocks` map, and they can
+ * race-prune each other's per-ref dirs (see `pruneOldRefDirs` in each
+ * source impl). v1 assumes one cache owner per workspace. If we ever
+ * need multi-process sharing, replace this with a filesystem advisory
+ * lock (e.g. `proper-lockfile` against `${root}/.lock`) around
+ * fetch+prune.
+ *
+ * The map stores the *guarded* (error-swallowed) promise so a rejection in
+ * `fn` doesn't poison the chain. Identity comparison in `finally` uses the
+ * same stored reference, so cleanup actually removes the entry — an
+ * earlier draft created a fresh `.catch()` inside `finally` and leaked one
+ * entry per distinct URI.
+ */
+const _sourceLocks = new Map();
+export async function withSourceLock(uri, fn) {
+    const prev = _sourceLocks.get(uri) ?? Promise.resolve();
+    const next = prev.then(fn, fn);
+    const guarded = next.catch(() => undefined);
+    _sourceLocks.set(uri, guarded);
+    try {
+        return await next;
+    }
+    finally {
+        if (_sourceLocks.get(uri) === guarded) {
+            _sourceLocks.delete(uri);
+        }
+    }
+}
+/** Default cache root: `WORKSPACE_DIR` env, else `process.cwd()`. */
+export function defaultCacheRoot() {
+    return process.env.WORKSPACE_DIR ?? process.cwd();
+}
+export async function readManifest(path) {
+    try {
+        const raw = await readFile(path, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return null;
+        throw err;
+    }
+}
+export async function writeManifest(path, manifest) {
+    await writeFile(path, JSON.stringify(manifest, null, 2), 'utf8');
+}
+export async function readMeta(path) {
+    try {
+        const raw = await readFile(path, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return null;
+        throw err;
+    }
+}
+export async function writeMeta(path, meta) {
+    await writeFile(path, JSON.stringify(meta, null, 2), 'utf8');
+}
+/**
+ * Diff two manifests by `(path, sha256)`. Order-independent.
+ */
+export function diffManifests(prev, next) {
+    const prevMap = new Map(prev.files.map((f) => [f.path, f.sha256]));
+    const nextMap = new Map(next.files.map((f) => [f.path, f.sha256]));
+    const added = [];
+    const modified = [];
+    const removed = [];
+    for (const [path, sha] of nextMap) {
+        const prevSha = prevMap.get(path);
+        if (prevSha === undefined)
+            added.push(path);
+        else if (prevSha !== sha)
+            modified.push(path);
+    }
+    for (const path of prevMap.keys()) {
+        if (!nextMap.has(path))
+            removed.push(path);
+    }
+    return { added, modified, removed };
+}
+/**
+ * Canonicalize a manifest's `ref` from its file list:
+ *
+ *  sha256 over lines of `<path>\0<sha256>\n`, sorted by path.
+ *
+ * Deterministic across runs and platforms.
+ */
+export function canonicalManifestRef(files) {
+    const sorted = [...files].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    const h = createHash('sha256');
+    for (const f of sorted) {
+        h.update(f.path);
+        h.update('\0');
+        h.update(f.sha256);
+        h.update('\n');
+    }
+    return h.digest('hex');
+}
+//# sourceMappingURL=cache.js.map

package/dist/sources/cache.js.map

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

package/dist/sources/git-file-source.d.ts

@@ -0,0 +1,33 @@
+/**
+ * GitFileSource — shallow git clone backed by `isomorphic-git`.
+ *
+ *  - URI shape: `git+https://github.com/owner/repo.git[@<ref>]`. Ref may be
+ *    a branch name, tag, or full commit SHA. If omitted, defaults to `main`.
+ *  - Initial fetch: shallow clone (`depth: 1`, `singleBranch: true`).
+ *  - Subsequent fetch: `git.fetch` against the same single branch with
+ *    `depth: 1` — pulls only the new tip if upstream advanced.
+ *  - `ref` = `resolveRef('HEAD')` (full commit SHA).
+ *  - `diffSinceRef(prevRef)` walks two trees with `git.walk` and classifies
+ *    each path by OID equality (`added`/`modified`/`removed`).
+ *
+ * Caveats called out in JSDoc rather than hidden:
+ *
+ *  - With `depth: 1`, history before the current tip is NOT in the local
+ *    repo. `git.walk` requires both trees to be reachable; if the caller
+ *    passes a `prevRef` we no longer have on disk we throw a clear error.
+ *  - Snapshot reads point at the working tree inside the cache. Git itself
+ *    is not exposed.
+ */
+import type { FileDelta, FileSystemSource, Snapshot } from '../file-source.js';
+export interface ParsedGitUri {
+    url: string;
+    ref: string;
+}
+export declare function parseGitUri(uri: string): ParsedGitUri;
+export declare class GitFileSource implements FileSystemSource {
+    #private;
+    constructor(uri: string);
+    fetch(): Promise<Snapshot>;
+    diffSinceRef(prevRef: string): Promise<FileDelta>;
+}
+//# sourceMappingURL=git-file-source.d.ts.map

package/dist/sources/git-file-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-file-source.d.ts","sourceRoot":"","sources":["../../src/sources/git-file-source.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAUH,OAAO,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAiB/E,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;CACb;AAED,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,CAkBrD;AAED,qBAAa,aAAc,YAAW,gBAAgB;;gBAKxC,GAAG,EAAE,MAAM;IAMvB,KAAK,IAAI,OAAO,CAAC,QAAQ,CAAC;IAmD1B,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC;CA2DlD"}