Loomworks Investigation — The Companion source-provider abstraction (external data, real-time feeds, databases, oracles) — v0.1

Document: loomworks-investigation-companion-source-provider-abstraction-v0_1 Version: v0.1 Date: 2026-06-29 Provenance: Claude.ai scoping/Discovery session. Operator: Marvin Percival. Arose from a request to look at "web requests and resolution of returned text into Companion" plus "local time (machine) and other inaccessible information," which the Operator immediately widened to "real-time feeds, databases knowledge, oracle data" with the instruction to scope the full abstraction, not the immediately-identified cases. Status: Investigation / scoping document. Architecture direction, NOT a build order. Generalizes queued-directions §8 (external information seams / the gateway) and composes with §9 (Companion ambient context). Canonical home: loomworks-record. Trajectory preserved (the §8 REST-gateway scope → the Operator's "scope wider" reframe → the generalized provider abstraction).

Plain-language summary

The Companion is useful partly because it can compose two kinds of fact: universal facts anyone could find (the time, the weather, a price, a row in a database) and specific facts only the Operator has (their time-zone, their schedule, their pending work) — and the value is in combining them. This document is about the universal half: where those facts come from. The existing design (§8) scoped a gateway for public REST APIs. But the Operator named that the real sources are broader — real-time streaming feeds, the Operator's own databases, authoritative "oracle" data (both blockchain oracles and source-of-truth feeds). These have different access shapes (you fetch an API, you subscribe to a feed, you query a database, you trust an oracle), but they share the same discipline (declared not hard-coded, attested per use, credential-scoped, definition held as Memory). So instead of building a REST gateway and bolting the rest on as exceptions, the architecture should be one discipline, many provider kinds — the REST gateway becomes one kind among several, and new kinds (streaming, database, oracle, sensor, MCP, document store) are added by declaration, not rebuilt. This is the same "build once, configure N" reframe that made the gateway load-bearing, generalized one level up.

1. What's already settled (the foundation this extends)

This investigation does not start fresh — it generalizes filed architecture. The pieces it rests on:

The ambient-context decomposition (queued-directions §9.2). Contextual/ambient questions decompose into:

• Universal component — findable by anyone, not Operator-specific (the time, the weather, a price, an exchange rate, a public record).
• Specific component — supplied by personal/engagement Memory (the Operator's time-zone, location, schedule, the engagement's parameters).
• Bridge (optional) — Companion reasoning that combines them ("it's 09:13, your 09:30 is across town, traffic is light, leave in 8 minutes").

Load-bearing thesis (the supplied-domain thesis applied to ambient context): universal facts are findable; the specific has to be supplied; the value is in the composition. This document is about sourcing the universal component — and the recognition here is that "universal component" has many source kinds, not one.

The external gateway (queued-directions §8.1). One specialist for external data, configuration-driven via the Phase-38 declare-and-register pattern ("adding a source is a declaration, not a release"), FORAY-attested per call, OVA-scoped credentials. Four progressive tiers (Tier 1 simple GET; Tier 2 OAuth/pagination/rate-limits; Tier 3 response transformation through engagement-declared schemas; Tier 4 cross-service semantic mapping). The reframe that made it load-bearing: "build one gateway, let the source definitions live as Memory" instead of shipping N first-party adapters.

The methodology recognition under §8.1. External source specifications are themselves a class of supplied domain knowledge. The gateway is the discipline; the catalog of source-definitions held as Memory is the domain. Information already in the world becomes useful AI context only when it's held as Memory the Companion reasons against, not retrieved ad-hoc.

The protocol triangle at the seam. Loom holds the source definitions; OVA scopes the credentials; FORAY attests every access. This triangle is the discipline that stays invariant across everything below.

The composing pieces that exist. Phase 41 personal Memory (the specific component's home), Phase 42 reactive Companion (intent classification — recognizing a contextual question), Phase 44 SSE/proactive substrate (the push channel — load-bearing for streaming providers below), Phase 34 polling, Phase 38 declare-and-register (the configuration mechanism), OVA credential storage, the FORAY attestation surface.

2. The reframe the generalization

§8 scoped the universal source as "a public REST API you GET from." The Operator's widening names that this is one access shape among several. The sources that matter — real-time feeds, the Operator's databases, oracle data — do not fit a request/response REST gateway:

• A real-time feed is not fetched, it is subscribed to. The "current value" is a continuously-updated standing fact (a market tick, a sensor reading, a status stream). This breaks the GET model — it is a standing subscription, and it lands on the Phase-44 SSE/proactive substrate, not the polling path.
• A database is a credentialed query against structured data the Operator already has access to (their warehouse, an internal SQL/NoSQL store). Different auth (connection strings, not API keys), different result shape (result sets, not JSON docs), and a real trust question (the Companion querying the Operator's own data, not a public source).
• An oracle is a designated authoritative source whose attestation matters — and the Operator confirmed BOTH senses (see §4): the blockchain oracle (Chainlink-style attested on-chain truth) and the general source-of-truth feed (a price oracle, a reference-data registry, a record-of-truth).

The invariant under all of them: the access shape differs (fetch / subscribe / query / trust), but the surrounding discipline is identical — declared not released (Phase 38), FORAY-attested, OVA-scoped, definition-held-as-Memory, composed with specific-from-Memory (§9.2), surfaced through the Companion. So the architecture is not "a gateway plus exceptions"; it is one discipline parameterized over a provider-kind taxonomy. The §8 REST gateway is one provider kind (request/response) within this — its four tiers become the request/response kind's internal sophistication ladder, not the whole architecture.

This is the same reframe that made §8 load-bearing, one level up. §8 converted "ship N adapters" → "build one gateway, configure N sources." This converts "build one gateway" → "build one provider discipline, add provider kinds (and within each kind, N sources)." Build-once-configure, generalized.

3. The source-provider abstraction

3.1 The invariant (what every provider shares)

Every source-provider, regardless of kind, carries:

• A declared definition (Phase 38) — held as Memory (the supplied-domain recognition). Adding a source is a declaration: its endpoint/connection/topic, its auth requirement, its result schema, its freshness model. Not a code release.
• OVA-scoped credentials — the access is authorized at the OVA seam; the provider never holds raw secrets ad-hoc.
• FORAY attestation per access — every fetch/subscribe-tick/query/oracle-read is attested at the auditable event layer (the engine substrate, the 16 reserved seams — NOT the surface; the standing FORAY-at-the-substrate discipline). Trust does not depend on the Companion surface cooperating.
• A result, normalized to a Memory-composable shape — so the universal component can compose with the specific component (§9.2). The "resolution of returned text" the Operator originally named is this normalization step: provider output → a fact the Companion can reason against.
• A freshness contract (§3.3) — how current the result must be, and whether it is pull or push.

3.2 The provider-kind taxonomy (extensible, NOT closed)

Each kind has a different access shape; the invariant (§3.1) is identical across all.

| Kind | Access shape | Auth model | Result shape | Freshness | Example | |---|---|---|---|---|---| | Request/response (= §8's gateway, repositioned) | fetch (GET/POST) | API key / OAuth | JSON/XML doc | pull, cacheable | weather, FX, geocoding, holidays, public-apis catalog | | Engine-internal | direct read | none (in-system) | scalar/struct | pull, no cache | machine local time (the canonical trivial case), server date, system state | | Streaming / real-time feed | subscribe | token / connection | continuous ticks | push, standing | market ticks, sensor streams, status feeds, pub/sub topics — lands on Phase-44 SSE | | Database | query | connection string / scoped creds | result set (rows) | pull, on-demand, credentialed | the Operator's warehouse, an internal SQL/NoSQL store, a record system | | Oracle — attested (blockchain sense) | read attested value | chain RPC / OVA | attested datum + proof | point-in-time, attested | Chainlink-style price/reference oracle; FORAY-kindred (§4) | | Oracle — source-of-truth (authority sense) | read designated authority | varies | authoritative datum | point-in-time, authoritative | a reference-data registry, a record-of-truth, a designated price source (§4) | | Sensor / device (likely) | read / subscribe | device creds | reading | pull or push | IoT, FarmGuard-class field sensors | | MCP server (likely) | tool call | MCP auth | tool result | per-call | an MCP-exposed capability as a provider | | Document / file store (likely) | fetch / search | scoped creds | document/chunk | pull, cacheable | an internal doc store, an uploaded-corpus seam |

The bottom three are flagged likely — named so the taxonomy is open, not to commit them. The discipline (§3.1) is what's fixed; the kind list grows by declaration.

3.3 The freshness / temporality axis (orthogonal to kind)

A second axis the Operator's list surfaces, independent of kind: how current must the value be, and is it pull or push. This separates "what time is it" (pull, no cache) from "the BTC price" (push, streaming) from "this quarter's revenue" (query, on-demand) even though those touch three different kinds. The freshness contract on each declared source carries:

• Cadence — instantaneous-on-demand / cache-with-TTL / standing-subscription / point-in-time-attested.
• Direction — pull (Companion fetches when a question arises) vs. push (the source updates a standing fact the Companion already holds — the streaming/ambient case, Phase-44).
• Staleness tolerance — how old a cached value may be before re-access. (Time: zero. Weather: ~1h. A held reference table: long.)

Freshness × kind compose: a "database" kind can be pull-on-demand or (with CDC/change-feed) push-standing; an "oracle" can be point-in-time or subscribed. So the provider record is (kind, freshness-contract, definition) — the kind sets the access shape, the freshness contract sets the temporality, the definition supplies the specifics. This keeps the design additive: a new combination is a new declared row, not new code.

4. Oracle both senses (the Operator confirmed both)

The Operator confirmed "oracle" means both the blockchain sense and the authoritative-source sense. The investigation treats them as two provider kinds sharing one recognition: some universal facts come from a designated authority whose attestation is the point.

• Attested oracle (blockchain). Chainlink-class: external truth fed with cryptographic attestation. This is FORAY-kindred — FORAY already attests transactions at the auditable layer; an attested oracle is an external attestation source the Companion consumes. The notable composition: a value read from an attested oracle arrives with a proof, and FORAY attests that the Companion consumed that proven value — attestation-on-attestation, a clean fit with the protocol triangle. Worth a deeper look when an engagement needs on-chain/attested external truth (DeFi, supply-chain provenance, any "prove the external fact was X at time T" requirement).
• Source-of-truth oracle (authority). The general case: a designated record-of-truth (a reference-data registry, a canonical price source, a registry-of-record). No cryptographic proof, but authority — the value is trusted because of where it came from, and that provenance is recorded. This is the provenance-thread model (each fact carries typed origin threads; trust is tie-to-source) applied to external authority.

Both reduce to: the provider declaration carries an authority/attestation descriptor — for the blockchain kind, a verifiable proof; for the authority kind, a recorded provenance to a designated source. Same slot, different fill. This is the cleanest unification: oracle-ness is an attestation property on the provider, composing with the FORAY-at-the-substrate and provenance-thread disciplines already filed.

5. How this composes with the existing architecture

• §9.2 ambient decomposition — providers (§3) supply the universal component; personal Memory supplies the specific; the Companion bridges. This investigation is the sourcing layer under §9.2. "Machine local time" is the engine-internal kind composed with a time-zone assertion in Memory — the canonical trivial instance, and the first one worth building (it lays the pattern).
• §8 gateway — repositioned as the request/response kind. Its four tiers become that kind's sophistication ladder. Nothing in §8 is lost; it's located within the broader abstraction.
• Phase 38 declare-and-register — the mechanism for adding any provider (any kind). The consumer side of declare-and-register for an external-data class, now generalized across kinds.
• Phase 44 SSE/proactive — the push channel the streaming kind lands on. The reason streaming isn't a hack: the substrate already has a push path; streaming providers feed standing facts through it.
• Protocol triangle (Loom/OVA/FORAY) — the invariant discipline (§3.1). Loom holds the definitions, OVA scopes credentials, FORAY attests access — across all kinds.
• Provenance threads / FORAY-at-substrate — the oracle attestation descriptor (§4) composes with these directly.
• Standing Companion (§10) — a provider can feed the standing Companion's ambient model (push/streaming), not only answer an engaged question — the ambient-posture connection.

6. The methodology recognition (candidate finding)

Worth naming so it isn't lost: the universal component of context is sourced by a provider abstraction invariant across access shapes; provider-kind is a parameter, not an architecture. This is the §8 build-once-configure reframe generalized: the discipline (declared / attested / scoped / Memory-held / Memory-composable / freshness-contracted) is fixed; kind (fetch/subscribe/query/attest) and freshness (pull/push, TTL) are orthogonal parameters; new sources are declared rows, new kinds are occasional discipline-preserving additions. The same supplied-domain thesis applies: a source definition is supplied domain knowledge held as Memory; the value is in composing the universal it yields with the Operator's specific. Candidate for v0.21 methodology consolidation, alongside §8.1's "external specs are supplied domain" and §9.2's ambient decomposition — this is their unification.

7. Build boundary what's now vs. what's deferred

This is a scoping/investigation document. Nothing here is a build order. The discipline of the session (strip-it-down; build only what an engagement makes load-bearing) applies in full — the abstraction is exciting precisely when over-building is the risk.

The one small, real, shippable first instance (when chosen): machine local time — the engine-internal kind composed with an Operator time-zone Memory assertion (§9.2's canonical trivial case). It fixes a visible gap (the Companion can't tell the Operator their own local time) AND, built to the provider/decomposition shape, it lays the pattern as the first instance rather than a one-off. Its real prerequisite is the time-zone (and location) being capturable/held as a personal-Memory assertion — to be grounded against the live codebase before scoping the build.

Named, deferred (NOT build-now):

• The request/response gateway (§8) proper — its build trigger remains "the second engagement needing live external data on the hot path."
• Streaming/real-time providers — when an engagement makes a live feed load-bearing (FarmGuard sensors, a market-data engagement).
• Database providers — when an engagement needs to query the Operator's own structured data.
• Oracle providers (either sense) — when an engagement needs attested/authoritative external truth (DeFi, provenance, reference-data).
• The standing ambient-context posture (§9.1) as a coherent built capability — the composing layer; methodology-grade, surfaces with the mobile-presence engagement.

Build trigger discipline (general): a provider kind gets built when an engagement makes that kind load-bearing on the hot path — not speculatively. The abstraction exists so that when the trigger fires, the work is a declaration within a known discipline, not a fresh design.

8. Open questions (for when a build trigger fires)

• Database trust scope. The Companion querying the Operator's own database is a new trust surface (it can read structured data the Operator owns). What scopes the queries — OVA read-scopes per table/view? Operator-declared query allow-lists? Worth settling before the database kind is built.
• Streaming cost/lifecycle. A standing subscription has ongoing cost and a lifecycle (connect, reconnect, teardown). How does a streaming provider's lifecycle bind to an engagement's lifecycle? (Subscription ends when the engagement closes? Stays standing for the standing Companion?)
• Oracle attestation surface. For the blockchain kind, where does proof verification happen — engine-side (FORAY-adjacent) so the surface can't forge it? (Lean: yes, substrate-side, per FORAY-at-substrate.)
• Provider-definition authoring. Adding a provider is a Phase-38 declaration — but who authors it and through what surface? (The Discovery-to-seed flow's "what external info does this need" question, per §8.2? A provider-catalog engagement?)
• The vocabulary. "Provider", "source", "seam", "feed" — settle the methodology noun for this construct before it proliferates (plain-terms discipline). Lean: source-provider (or just provider) as the construct; seam stays the connection-point term §8 already uses.

Companion documents

• loomworks-queued-directions-and-deferred-work (§8 external information seams, §9 Companion ambient context, §10 standing Companion) — the filed directions this generalizes; §8's gateway becomes the request/response kind here.
• loomworks-white-label-multilanguage-analysis-v0_1 and the vocabulary-resolver standing note — adjacent supplied-domain / configuration-driven patterns.
• The Loomworks seed + architecture spec — FORAY-at-substrate, OVA scoping, the protocol triangle, provenance threads.

DUNIN7 — Done In Seven LLC — Miami, Florida Loomworks Investigation — The Companion source-provider abstraction — v0.1 — 2026-06-29 Generalizes the §8 external gateway (scoped for public REST APIs) into a source-provider abstraction: ONE invariant discipline (declared via Phase 38, OVA-scoped, FORAY-attested per access, definition-held-as-Memory, normalized to a Memory-composable result, freshness-contracted) parameterized over an EXTENSIBLE provider-kind taxonomy (request/response = the old gateway; engine-internal = machine local time; streaming/real-time = Phase-44 SSE; database = credentialed query; oracle in BOTH senses — blockchain-attested, FORAY-kindred, and source-of-truth-authority; plus likely sensor / MCP / document-store) and an orthogonal freshness/temporality axis (pull/push, TTL, point-in-time-attested). Sources the universal component of the §9.2 ambient decomposition; composes with personal Memory (specific) + Companion bridge. Build-once-configure generalized one level up: new sources are declared rows, new kinds discipline-preserving additions. First shippable instance: machine local time (engine-internal kind + time-zone Memory assertion). Everything else deferred to its engagement build trigger. Trajectory preserved: §8 REST scope → Operator "scope wider" → provider abstraction.