Class: FilesystemSource¶

WHERE — load documents from storage.

v1.0 async refactor: read methods return Promise<...> so adapters with non-local backends (Postgres, HTTP, S3) can implement them naturally. Filesystem adapter wraps sync impls in Promise.resolve for back-compat.

Implements¶

SourcePort

Constructors¶

Constructor¶

new FilesystemSource(baseDir): FilesystemSource;

Parameters¶

Parameter	Type
`baseDir`	`string`

Returns¶

FilesystemSource

Properties¶

baseDir¶

readonly baseDir: string;

supportsReaders¶

readonly supportsReaders: true = true;

Implementation of¶

SourcePort.supportsReaders

Methods¶

capabilities()¶

capabilities(): SourceCapabilities;

Explicit contract declaration (s-sourceport-contract-cleanup) — kept honest by the adapter conformance test (declaration == structural derivation). Read-only FS source: in-memory query/count + the L1 granular reads (loadOne + listDocRefs, s-dna-port-surface-parity); no bundle/write surface on the TS twin yet.

Returns¶

SourceCapabilities

Implementation of¶

SourcePort.capabilities

close()¶

close(): Promise<void>;

Documented NO-OP — the FS source holds no pooled resources (each read opens/closes its own file handles via fs/promises). The member exists for SourcePort surface parity with Python, where close is a SOURCE_PORT_CORE_MEMBERS boot-gate entry.

Returns¶

Promise\<void>

Implementation of¶

SourcePort.close

count()¶

count(
   scope, 
   kind, 
opts?): Promise<CountResult>;

Two-planes F2 — record-plane count over loadAll + countDocs (mirror of the Py protocol-default). Same opts.tenant NO-OP caveat as query.

Parameters¶

Parameter	Type
`scope`	`string`
`kind`	`string`
`opts`	`SourceCountOpts`

Returns¶

Promise\<CountResult>

Implementation of¶

SourcePort.count

listDocRefs()¶

listDocRefs(scope, opts?): Promise<[string, string][]>;

L1 granular access — FS impl projects from loadAll (mirror of the Py FilesystemSource.list_doc_refs): [kind, name] refs only, no bundle rehydration. No perf gain over loadAll on FS, but keeps the SourcePort contract consistent across adapters (PG is where the gain lives). Tenant: union of base + overlay with the overlay shadowing base, same as the Py twin. Result sorted by (kind, name).

Parameters¶

Parameter	Type
`scope`	`string`
`opts?`	{ `kind?`: `string` \| `null`; `tenant?`: `string` \| `null`; }
`opts.kind?`	`string` \| `null`
`opts.tenant?`	`string` \| `null`

Returns¶

Promise\<[string, string][]>

Implementation of¶

SourcePort.listDocRefs

loadAll()¶

loadAll(scope, readers?): Promise<Record<string, unknown>[]>;

Parameters¶

Parameter	Type
`scope`	`string`
`readers?`	`ReaderPort`[]

Returns¶

Promise\<Record\<string, unknown>[]>

Implementation of¶

SourcePort.loadAll

loadBootstrapDocs()¶

loadBootstrapDocs(scope, opts?): Promise<Record<string, unknown>[]>;

Phase 16 — return the docs the kernel needs registered/parsed BEFORE loadAll fires (Genome + KindDefinition + LayerPolicy). Adapters that can filter cheaply (SQL WHERE kind IN (...)) SHOULD do so. Filesystem adapters MAY return a superset.

Tenant semantics: when opts.tenant is set, the tenant-published Genome shadows the platform Genome (Phase 9 multi-tenant publishing). KindDefinition + LayerPolicy stay platform-only (non-overlayable per Phase 16).

1:1 parity with Python SourcePort.load_bootstrap_docs.

Parameters¶

Parameter	Type
`scope`	`string`
`opts?`	{ `tenant?`: `string`; }
`opts.tenant?`	`string`

Returns¶

Promise\<Record\<string, unknown>[]>

Implementation of¶

SourcePort.loadBootstrapDocs

loadLayer()¶

loadLayer(
   scope, 
   layerId, 
   layerValue, 
readers?): Promise<Record<string, unknown>[]>;

Parameters¶

Parameter	Type
`scope`	`string`
`layerId`	`string`
`layerValue`	`string`
`readers?`	`ReaderPort`[]

Returns¶

Promise\<Record\<string, unknown>[]>

Implementation of¶

SourcePort.loadLayer

loadOne()¶

loadOne(
   scope, 
   kind, 
   name, 
opts?): Promise<Record<string, unknown> | null>;

L1 granular access — FS impl projects from loadAll (mirror of the Py FilesystemSource.load_one). No perf gain over loadAll on FS (cheap in-process disk reads) but keeps the SourcePort contract consistent across adapters. Tenant overlay shadows base: when opts.tenant is set the tenant layer is consulted first and the BASE layer is the fallback (same as Python — a tenant read of a doc with no overlay still returns the base doc).

Parameters¶

Parameter	Type
`scope`	`string`
`kind`	`string`
`name`	`string`
`opts?`	{ `readers?`: `ReaderPort`[]; `tenant?`: `string` \| `null`; }
`opts.readers?`	`ReaderPort`[]
`opts.tenant?`	`string` \| `null`

Returns¶

Promise\<Record\<string, unknown> | null>

Implementation of¶

SourcePort.loadOne

query()¶

query(
   scope, 
   kind, 
opts?): AsyncIterable<Record<string, unknown>>;

Two-planes F2 — record-plane query over loadAll + the shared pure helpers (mirror of the Py SourcePort.query protocol-default). FS is dev-mode with small scopes; native push-down is the purview of the SQL adapters.

opts.tenant is a documented NO-OP here: the FS TS adapter has no tenant-aware overlay merge in loadAll (divergence from the Py FS source, which unions base + tenant layer with shadowing) — overlay support is an F2.5 candidate alongside the writable FS source.

Bundle-format kinds are not visible to this query (no kernel reader back-ref on the TS source) — record-plane docs are plain YAML.

Parameters¶

Parameter	Type
`scope`	`string`
`kind`	`string`
`opts`	`SourceQueryOpts`

Returns¶

AsyncIterable\<Record\<string, unknown>>

Implementation of¶

SourcePort.query

resolveRef()¶

resolveRef(scope, ref): Promise<string>;

Parameters¶

Parameter	Type
`scope`	`string`
`ref`	`string`

Returns¶

Promise\<string>

Implementation of¶

SourcePort.resolveRef