@cat-factory/kernel 0.83.0 → 0.84.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/ports/caching.d.ts
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import type { DocumentContent } from './document-source.js';
|
|
1
2
|
import type { ResolvedCatalogEntry } from './fragment-repositories.js';
|
|
2
3
|
/**
|
|
3
4
|
* A named, workspace-groupable read-through cache. `get` returns the cached
|
|
@@ -37,6 +38,16 @@ export interface GroupCacheHandle<T> {
|
|
|
37
38
|
export interface AppCaches {
|
|
38
39
|
/** The merged per-workspace prompt-fragment catalog, grouped by workspace id. */
|
|
39
40
|
fragmentCatalog: GroupCacheHandle<ResolvedCatalogEntry[]>;
|
|
41
|
+
/**
|
|
42
|
+
* The live body of a document-backed prompt fragment (the external
|
|
43
|
+
* Confluence/Notion/GitHub/… page), grouped by the workspace whose connection
|
|
44
|
+
* fetches it and keyed by `<source>:<externalId>`. A self-verifying cache: an
|
|
45
|
+
* entry entering its refresh window runs the source's cheap version probe and
|
|
46
|
+
* keeps its cached body when the page hasn't moved, so an agent run reads a
|
|
47
|
+
* fragment body without blocking on a live page fetch. Explicit writes (a
|
|
48
|
+
* fragment refresh/edit) invalidate it directly.
|
|
49
|
+
*/
|
|
50
|
+
fragmentDocumentBody: GroupCacheHandle<DocumentContent>;
|
|
40
51
|
/** Release notification-bus resources (a no-op for bare in-memory caches). */
|
|
41
52
|
close(): Promise<void>;
|
|
42
53
|
}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"caching.d.ts","sourceRoot":"","sources":["../../src/ports/caching.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAA;AAYtE;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB,CAAC,CAAC;IACjC;;;;;;;OAOG;IACH,GAAG,CACD,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACtB,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,GAC/C,OAAO,CAAC,CAAC,CAAC,CAAA;IACb,gFAAgF;IAChF,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACrD,8DAA8D;IAC9D,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC7C;;;;OAIG;IACH,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CAC/B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,SAAS;IACxB,iFAAiF;IACjF,eAAe,EAAE,gBAAgB,CAAC,oBAAoB,EAAE,CAAC,CAAA;IACzD,8EAA8E;IAC9E,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACvB"}
|
|
1
|
+
{"version":3,"file":"caching.d.ts","sourceRoot":"","sources":["../../src/ports/caching.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAC3D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAA;AAYtE;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB,CAAC,CAAC;IACjC;;;;;;;OAOG;IACH,GAAG,CACD,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACtB,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,GAC/C,OAAO,CAAC,CAAC,CAAC,CAAA;IACb,gFAAgF;IAChF,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACrD,8DAA8D;IAC9D,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC7C;;;;OAIG;IACH,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CAC/B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,SAAS;IACxB,iFAAiF;IACjF,eAAe,EAAE,gBAAgB,CAAC,oBAAoB,EAAE,CAAC,CAAA;IACzD;;;;;;;;OAQG;IACH,oBAAoB,EAAE,gBAAgB,CAAC,eAAe,CAAC,CAAA;IACvD,8EAA8E;IAC9E,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACvB"}
|
|
@@ -10,6 +10,15 @@ export interface DocumentContent {
|
|
|
10
10
|
url: string;
|
|
11
11
|
/** Body normalized to lightweight Markdown (consumed by the planner/excerpt). */
|
|
12
12
|
body: string;
|
|
13
|
+
/**
|
|
14
|
+
* Opaque version token for the fetched content — a value that changes iff the
|
|
15
|
+
* page changed (Confluence version number, Notion `last_edited_time`, a git
|
|
16
|
+
* commit sha, a design-file version). Comparable only by equality; it is the
|
|
17
|
+
* value {@link DocumentSourceProvider.probeVersion} returns, so the caching seam
|
|
18
|
+
* can confirm a cached body is still current with a cheap metadata probe instead
|
|
19
|
+
* of re-fetching the whole page. `''` when the source exposes no version.
|
|
20
|
+
*/
|
|
21
|
+
version: string;
|
|
13
22
|
}
|
|
14
23
|
/** The result of validating + normalizing connect credentials. */
|
|
15
24
|
export interface NormalizedConnection {
|
|
@@ -32,6 +41,14 @@ export interface DocumentSourceProvider {
|
|
|
32
41
|
parseRef(input: string): string | null;
|
|
33
42
|
/** Fetch a single page by its id using the connection credentials. */
|
|
34
43
|
fetchDocument(credentials: DocumentCredentials, externalId: string): Promise<DocumentContent>;
|
|
44
|
+
/**
|
|
45
|
+
* Cheaply read the page's current version token — the {@link DocumentContent.version}
|
|
46
|
+
* value {@link fetchDocument} would return, fetched with metadata only (no body
|
|
47
|
+
* download or Markdown conversion). MUST be strictly cheaper than `fetchDocument`,
|
|
48
|
+
* so the caching seam can bump a cached body's TTL when the token is unchanged
|
|
49
|
+
* instead of re-fetching. Returns `''` when the source exposes no version.
|
|
50
|
+
*/
|
|
51
|
+
probeVersion(credentials: DocumentCredentials, externalId: string): Promise<string>;
|
|
35
52
|
/**
|
|
36
53
|
* Search the source's catalogue by free text and return lean hits (no body).
|
|
37
54
|
* Optional: a provider that only supports paste-a-URL import omits it (and its
|
|
@@ -55,6 +72,13 @@ export interface DocumentSourceProvider {
|
|
|
55
72
|
export interface DocumentContentResolver {
|
|
56
73
|
/** Fetch the page's current content; throws when the source is unreachable / not connected. */
|
|
57
74
|
fetch(workspaceId: string, source: DocumentSourceKind, externalId: string): Promise<DocumentContent>;
|
|
75
|
+
/**
|
|
76
|
+
* Cheaply probe the page's current version token (see
|
|
77
|
+
* {@link DocumentSourceProvider.probeVersion}) — the staleness check the caching
|
|
78
|
+
* seam runs against a cached body's {@link DocumentContent.version}. Throws on the
|
|
79
|
+
* same unreachable/not-connected conditions as {@link fetch}.
|
|
80
|
+
*/
|
|
81
|
+
probeVersion(workspaceId: string, source: DocumentSourceKind, externalId: string): Promise<string>;
|
|
58
82
|
}
|
|
59
83
|
/** A lookup of the providers wired for this deployment, keyed by source. */
|
|
60
84
|
export interface DocumentSourceRegistry {
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"document-source.d.ts","sourceRoot":"","sources":["../../src/ports/document-source.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,kBAAkB,EAClB,wBAAwB,EACxB,oBAAoB,EACrB,MAAM,oBAAoB,CAAA;AAa3B,qEAAqE;AACrE,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;AAExD,0EAA0E;AAC1E,MAAM,WAAW,eAAe;IAC9B,2CAA2C;IAC3C,UAAU,EAAE,MAAM,CAAA;IAClB,KAAK,EAAE,MAAM,CAAA;IACb,qCAAqC;IACrC,GAAG,EAAE,MAAM,CAAA;IACX,iFAAiF;IACjF,IAAI,EAAE,MAAM,CAAA;
|
|
1
|
+
{"version":3,"file":"document-source.d.ts","sourceRoot":"","sources":["../../src/ports/document-source.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,kBAAkB,EAClB,wBAAwB,EACxB,oBAAoB,EACrB,MAAM,oBAAoB,CAAA;AAa3B,qEAAqE;AACrE,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;AAExD,0EAA0E;AAC1E,MAAM,WAAW,eAAe;IAC9B,2CAA2C;IAC3C,UAAU,EAAE,MAAM,CAAA;IAClB,KAAK,EAAE,MAAM,CAAA;IACb,qCAAqC;IACrC,GAAG,EAAE,MAAM,CAAA;IACX,iFAAiF;IACjF,IAAI,EAAE,MAAM,CAAA;IACZ;;;;;;;OAOG;IACH,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,kEAAkE;AAClE,MAAM,WAAW,oBAAoB;IACnC,0DAA0D;IAC1D,WAAW,EAAE,mBAAmB,CAAA;IAChC,4EAA4E;IAC5E,KAAK,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,sBAAsB;IACrC,yCAAyC;IACzC,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAA;IACjC,kFAAkF;IAClF,QAAQ,CAAC,UAAU,EAAE,wBAAwB,CAAA;IAC7C;;;OAGG;IACH,mBAAmB,CAAC,KAAK,EAAE,mBAAmB,GAAG,oBAAoB,CAAA;IACrE,mGAAmG;IACnG,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;IACtC,sEAAsE;IACtE,aAAa,CAAC,WAAW,EAAE,mBAAmB,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAAA;IAC7F;;;;;;OAMG;IACH,YAAY,CAAC,WAAW,EAAE,mBAAmB,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IACnF;;;;;;;;;;OAUG;IACH,MAAM,CAAC,CACL,WAAW,EAAE,mBAAmB,EAChC,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,oBAAoB,EAAE,CAAC,CAAA;CACnC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,uBAAuB;IACtC,+FAA+F;IAC/F,KAAK,CACH,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,kBAAkB,EAC1B,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,eAAe,CAAC,CAAA;IAC3B;;;;;OAKG;IACH,YAAY,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;CACnG;AAED,4EAA4E;AAC5E,MAAM,WAAW,sBAAsB;IACrC,+EAA+E;IAC/E,GAAG,CAAC,IAAI,EAAE,kBAAkB,GAAG,sBAAsB,GAAG,SAAS,CAAA;IACjE,4EAA4E;IAC5E,IAAI,IAAI,sBAAsB,EAAE,CAAA;CACjC"}
|