Diff: services/service-people.es
From c4d1fb1 to c4d1fb1
+0 / −0 lines
| Before | After |
|---|---|
| --- | --- |
| schema: foundry-doc-v1 | schema: foundry-doc-v1 |
| title: "service-people: Personnel Ledger" | title: "service-people: Personnel Ledger" |
| slug: service-people | slug: service-people |
| category: services | category: services |
| type: topic | type: topic |
| quality: complete | quality: complete |
| short_description: "service-people is the Ring 1 boundary-ingest service that maintains a deterministic flat-file personnel ledger, storing unique contact identifiers, communication states, and contact histories as a portable, schema-stable JSON flat-file database." | short_description: "service-people is the Ring 1 boundary-ingest service that maintains a deterministic flat-file personnel ledger, storing unique contact identifiers, communication states, and contact histories as a portable, schema-stable JSON flat-file database." |
| status: active | status: active |
| bcsc_class: public-disclosure-safe | bcsc_class: public-disclosure-safe |
| last_edited: 2026-05-08 | last_edited: 2026-05-08 |
| editor: pointsav-engineering | editor: pointsav-engineering |
| cites: [] | cites: [] |
| paired_with: service-people.es.md | paired_with: service-people.es.md |
| --- | --- |
| Every communication that enters the platform carries sender identity, and **service-people** is the Ring 1 boundary-ingest service that turns those identities into a queryable personnel ledger. The ledger is a directory of JSON flat files rather than a relational database — portable across infrastructure changes, auditable with standard filesystem tools, and natively compatible with local-model training pipelines that need a stable schema. service-people receives sender records from `service-extraction`, maintains contact state, and serves Ring 2 services that enrich content with contact context. | Every communication that enters the platform carries sender identity, and **service-people** is the Ring 1 boundary-ingest service that turns those identities into a queryable personnel ledger. The ledger is a directory of JSON flat files rather than a relational database — portable across infrastructure changes, auditable with standard filesystem tools, and natively compatible with local-model training pipelines that need a stable schema. service-people receives sender records from `service-extraction`, maintains contact state, and serves Ring 2 services that enrich content with contact context. |
| ## Architectural Baseline | ## Architectural Baseline |
| Every communication that enters through Ring 1 carries sender identity. service-people receives sender-identity records from service-extraction and maintains a persistent, queryable ledger of known contacts. Because the ledger is a flat-file JSON structure rather than a relational or document database, it can be copied, audited, and inspected with standard filesystem tools and does not require a running database process to remain readable. | Every communication that enters through Ring 1 carries sender identity. service-people receives sender-identity records from service-extraction and maintains a persistent, queryable ledger of known contacts. Because the ledger is a flat-file JSON structure rather than a relational or document database, it can be copied, audited, and inspected with standard filesystem tools and does not require a running database process to remain readable. |
| ## Ring and Role | ## Ring and Role |
| service-people occupies **Ring 1 — Boundary Ingest** in the three-ring architecture. Ring 1 services are per-tenant and implement an MCP (Model Context Protocol) server interface. service-people's role within Ring 1 is to maintain identity state: as communications arrive through service-email and other Ring 1 channels, service-people receives the parsed sender records from service-extraction and updates the contact ledger accordingly. Downstream Ring 2 services query service-people to enrich content with known contact context. | service-people occupies **Ring 1 — Boundary Ingest** in the three-ring architecture. Ring 1 services are per-tenant and implement an MCP (Model Context Protocol) server interface. service-people's role within Ring 1 is to maintain identity state: as communications arrive through service-email and other Ring 1 channels, service-people receives the parsed sender records from service-extraction and updates the contact ledger accordingly. Downstream Ring 2 services query service-people to enrich content with known contact context. |
| ## Structural Organization of Components | ## Structural Organization of Components |
| The service enforces the DS-ADR-02 flat-file standard, which rejects centralized database clusters in favour of a verifiable JSON flat-file state machine. The design choices that follow from this standard: | The service enforces the DS-ADR-02 flat-file standard, which rejects centralized database clusters in favour of a verifiable JSON flat-file state machine. The design choices that follow from this standard: |
| - **Portability.** The entire ledger is a directory of JSON files that can be moved to any system with a filesystem. No database migration is required. | - **Portability.** The entire ledger is a directory of JSON files that can be moved to any system with a filesystem. No database migration is required. |
| - **Schema stability.** JSON flat files do not require schema migrations when fields are added. Existing records remain valid as the schema evolves. | - **Schema stability.** JSON flat files do not require schema migrations when fields are added. Existing records remain valid as the schema evolves. |
| - **Auditability.** The ledger can be inspected, diffed, and versioned with standard tools. | - **Auditability.** The ledger can be inspected, diffed, and versioned with standard tools. |
| - **Model compatibility.** The flat-file format allows the ledger to feed local intelligence models directly, without an ETL step to extract from a database schema. | - **Model compatibility.** The flat-file format allows the ledger to feed local intelligence models directly, without an ETL step to extract from a database schema. |
| The service operates as a CLI tool. It exposes strictly defined query and update operations, processes sub-process calls from authorized execution adapters, and executes read and write operations against the JSON ledger files. | The service operates as a CLI tool. It exposes strictly defined query and update operations, processes sub-process calls from authorized execution adapters, and executes read and write operations against the JSON ledger files. |
| ## Configuration | ## Configuration |
| | Parameter | Purpose | | | Parameter | Purpose | |
| |---|---| | |---|---| |
| | Ledger path | Filesystem path for the JSON contact database | | | Ledger path | Filesystem path for the JSON contact database | |
| | Update adapter | Identity of the authorized process permitted to write contact records | | | Update adapter | Identity of the authorized process permitted to write contact records | |
| | Query interface | CLI flags for read operations against the ledger | | | Query interface | CLI flags for read operations against the ledger | |
| ## See Also | ## See Also |
| - [[service-email]] | - [[service-email]] |
| - [[service-extraction]] | - [[service-extraction]] |
| - [[service-search]] | - [[service-search]] |
| - [[trajectory-substrate]] | - [[trajectory-substrate]] |
| ## References | ## References |
| - §XI — Ring 1 boundary-ingest architecture and MCP server interface | - §XI — Ring 1 boundary-ingest architecture and MCP server interface |
| - `pointsav-monorepo/service-people/` — implementation crate | - `pointsav-monorepo/service-people/` — implementation crate |
| - DS-ADR-02 — flat-file state machine standard (files over databases) | - DS-ADR-02 — flat-file state machine standard (files over databases) |