Skip to content

PointSav Documentation

The engineering library for the PointSav platform — operating systems and services for regulated businesses that own their data, their AI, and their record-keeping outright. Where the monorepo holds the code, this wiki holds the reasoning: architecture, services, security, and the governance commitments that bind future development.

PointSav Digital Systems

DataGraph Federation: From app-orchestration-slm to app-orchestration-graph

← All revisions

71486d8b · PointSav Digital Systems ·

editorial(architecture): resolve app-orchestration-graph-federation's standing 2026-08-02 flag (Track-B) — confirmed real scaffold directly against src/main.rs/capability.rs: GET /v1/graph/context, ORCHESTRATION_GRAPH_TARGETS archive_name|endpoint|module_id triples, Ed25519 capability-forwarding, warnings/archives_queried/archives_responding fields, activation at >=2 archives not ~10; also fixed the 'current mechanism' section's overstated auth-gated claim (fan-out call itself carries no capability header today) and 2 pre-existing lint errors (duplicate H1, missing index_group); register-clean EN+ES

View the full record as of this revision →

@@ -10,13 +10,12 @@ bcsc_class: current-fact
language: en
paired_with: app-orchestration-graph-federation.es.md
category: architecture
index_group: platform-structure
status: active
quality: complete
last_edited: 2026-06-23
---

# DataGraph Federation: From app-orchestration-slm to app-orchestration-graph

Every [[totebox-archive|Totebox Archive]] in the PointSav platform maintains a sovereign DataGraph — a
graph of entities, relationships, and corpus metadata specific to its operational
domain. The GIS archive holds geographic entities and spatial relationships. The
@@ -52,9 +51,12 @@ os-orchestration sweeps Totebox DataGraphs. This is intentional — unsolicited 
from a sovereign archive would require a standing cross-archive capability grant,
which the architecture does not permit.

**Auth-gated.** Each Totebox Doorman validates the incoming query against its local
capability rules before exposing DataGraph data. The chassis cannot extract data that
the Totebox has not authorised for cross-archive access.
**Fire-and-forget fan-out.** The chassis's own outbound call to each Doorman carries
no signed capability header today — that's a property `app-orchestration-graph`
(below) adds when it activates, not something the current `app-orchestration-slm`
mechanism does yet. An unreachable archive is silently omitted from the response
rather than raising an error; the caller sees `archives_queried` against
`archives_reachable` and can tell the two numbers apart.

## Why app-orchestration-slm Holds Federation Now

@@ -92,33 +94,31 @@ of 20 or more Toteboxes, this connection pool is a non-trivial resource. Managin
inside `app-orchestration-slm` — which is designed to be a stateless routing process —
introduces operational complexity that a dedicated service handles naturally.

The expected activation threshold is approximately 10 active Totebox Archives with
non-trivial DataGraphs, or the appearance of a second consumer.

## What app-orchestration-graph Is Intended to Own

**Correction (2026-08-02, verified against canonical `origin/main`):** `app-orchestration-graph` isn't a future extraction target — it already exists as a substantial scaffold (`src/main.rs`, `src/capability.rs`), and its real, already-built design differs from every prediction below. The real endpoint is `GET /v1/graph/context`, not `POST /v1/graph/federated`; real archive discovery is a static `ORCHESTRATION_GRAPH_TARGETS` env var of `archive_name|endpoint|module_id` triples, not automatic FleetRegistry-based fanout; the real response includes `warnings`/`archives_queried`/`archives_responding` fields, not a `partial: true` flag; and the real code implements Ed25519 capability-forwarding/pairing, unmentioned anywhere below. Port `:9181` is independently confirmed correct. **Flagged, not resolved** — this section needs a rewrite around the real, already-shipped design rather than a still-future intent.

When extracted, `app-orchestration-graph` is intended to own:

- The `POST /v1/graph/federated` endpoint and all fanout logic (moved from
  `app-orchestration-slm`)
- A persistent connection pool to all registered Totebox `service-content` endpoints
- Partial-failure tolerance: a Totebox DataGraph that is unreachable returns a
  `partial: true` flag in the response, and the remaining results are returned rather
  than failing the whole query
- Result normalisation: cross-archive entity results would use a common canonical form
  regardless of per-archive DataGraph schema variations
- Query caching (short TTL, configurable per query type): federation is expensive at
  scale; a 30-second cache on stable entity queries is intended to avoid redundant
  fanout
`app-orchestration-graph` activates when the fleet reaches two Totebox Archives with
DataGraph endpoints, or when a second consumer of federated queries emerges —
whichever comes first.

## What app-orchestration-graph owns

`app-orchestration-graph` already exists as a working scaffold, not yet activated in
production. It serves `GET /v1/graph/context?q=&module_id=`, fanning out to every
target listed in the `ORCHESTRATION_GRAPH_TARGETS` environment variable — a
comma-separated list of `archive_name|endpoint|module_id` triples, so each target
carries its own tenant scope explicitly rather than being inferred from a bare URL.
Each fan-out call carries a signed `X-Foundry-Capability` header, established at
startup via an Ed25519 pairing handshake with each target; a target's own
capability gate rejects a query whose signed scope doesn't match the `module_id` it
was queried under. Entities returned from different archives are deduplicated by
normalised name. The response reports `warnings`, `archives_queried`, and
`archives_responding` rather than a single `partial` flag — a caller can see exactly
which archives answered and which didn't, not just whether the query was complete.

Planned port: `:9181` (`:9180` is `app-orchestration-slm`).

## What app-orchestration-graph Will NOT Own
## What app-orchestration-graph does not own

`app-orchestration-graph` will not hold entity data, replicate DataGraphs, or push
anything to Toteboxes. It is a read-only gateway. The source of truth for every entity
`app-orchestration-graph` holds no entity data, replicates no DataGraph, and pushes
nothing to Toteboxes. It is a read-only gateway. The source of truth for every entity
remains the `service-content` instance in the Totebox that generated it.

The name `app-orchestration-content` was considered and explicitly rejected. It would
Important Information

Corporate structure. PointSav Digital Systems ("PointSav") is currently a trade name of Woodfine Capital Projects Inc. ("Woodfine"), planned to become a wholly-owned Woodfine subsidiary upon incorporation. PointSav does not itself offer, sell, or solicit any security. Any securities offering associated with Woodfine's real-property direct-hold solutions is made exclusively by Woodfine, and only by means of the applicable Private Placement Memorandum.

No investment advice. This wiki's content is provided for engineering, operational, research, and development purposes. Nothing on this wiki constitutes investment advice or a solicitation to invest in any Woodfine partnership or direct-hold solution.

Intellectual property. The PointSav name, trade name, wordmark, and marks, together with all current and future PointSav- and Totebox-branded products, services, and offerings — and the software, source code, documentation, design system, and all related materials — are proprietary to Woodfine and its affiliates, except for components identified as open source. No rights are granted except as expressly set out in a written license or agreement. The full trademark notice appears in the footer of every page on this site.

Open source components. Portions of the platform are made available under permissive open-source licenses identified in the accompanying repository. Use of those components is governed by their respective license terms.

No warranty; informational use. Content on this wiki is provided for general informational purposes only and does not constitute a representation, warranty, or commitment with respect to product functionality, availability, pricing, or roadmap. Some articles describe planned or intended features, capabilities, and milestones — language such as "planned," "intended," "targeted," "may," and "expected" marks this forward-looking content, which is subject to change and does not constitute a commitment regarding future performance.

Confidentiality. Where an article describes an operational or deployment detail that is not intended for public disclosure, that article is not published on this wiki. Content here is general-purpose engineering documentation, not customer-specific configuration.

Jurisdiction. Woodfine Capital Projects Inc. is organized in British Columbia, Canada. References to the Sovereign Data Foundation on this wiki describe a planned or intended initiative only, not a current equity holder or active governance body.

Changes to this notice. PointSav may update this notice from time to time; the version posted on this page governs.

Not a filing system. This wiki is not a securities filing system, an electronic disclosure repository, or a substitute for SEDAR+ or any other regulatory filing system. Formal securities filings are made through the applicable regulatory filing system, not through this wiki.

Full disclaimer. This notice supplements, and does not replace, the full Disclaimers article. In the event of any conflict, the full Disclaimers article governs.

Read the full disclaimer →