-------------------------------------------------------------------------------- DOCUMENT CONTROL (HEADER) -------------------------------------------------------------------------------- Document ID : DARX_TECH_SPEC_001 Title : Document Publish Pipeline and Visibility Contract for the Daralbeida Multi-Entity Platform Version : 1.0 Status : IN_REVIEW Classification : Internal; sharable with contractors and AI tools on onboarding Prepared By : Claude (Sonnet 4.6) for PYB / Daralbeida Reviewed By : (pending) Approved By : (pending) Approval Date : (pending) Owner : PYB / Daralbeida Date Created : 2026-06-16 Last Revised : 2026-06-16 03:08 UTC Update Cycle : 90 days Next Review Due : 2026-09-14 Annual Review : 2027-06-16 Retention : Duration of Daralbeida operations; superseded versions kept indefinitely in Archives Department : TECH Style : BPGP Keywords : document registry, publish, visibility, doc_status.csv, render_portal, document library, section page, integrity, high-water marker, entity scope, live status, scan gating Related Docs : (none) Supersedes : (none) Superseded By : (none, current version) -------------------------------------------------------------------------------- OUTLINE -------------------------------------------------------------------------------- 1. Purpose and Scope 1.1 What This Document Is 1.2 What It Covers 1.3 Relation to the Code 2. Registry, the Single Source of Truth 2.1 The CSV and Its Editor 2.2 Classification Columns 2.3 The Multi-Value Entities Column 3. Publish Pipeline, Drop to Live 3.1 The Four Steps 3.2 Status Lifecycle in Practice 4. Visibility Rules, One Per Surface 4.1 The Rule Table 4.2 Single-Source Discipline 4.3 Entity-Scope Normalization 5. Integrity Guard, the Registry CSV 5.1 The Failure It Prevents 5.2 The High-Water Marker 5.3 Read Recovery and Write Refusal 6. Scan Gating, Cost Control 6.1 The Folder Signature 6.2 When a Scan Runs 7. AI Prompts 8. Revision History 9. Acronyms 10. Glossary -------------------------------------------------------------------------------- ================================================================================ 1. PURPOSE AND SCOPE ================================================================================ 1.1 WHAT THIS DOCUMENT IS This document is the controlling reference for how a document becomes visible on the Daralbeida internal platform: how it is registered, classified, published to a section page, and how the platform protects the registry that drives all of this. It records the contract that the platform code implements, so that a reader who has never seen the code can understand the publish behaviour, and so that a future change is made in the one correct place rather than copied across surfaces. 1.2 WHAT IT COVERS This document covers four things: the registry CSV that is the single source of truth for document classification; the four-step pipeline that moves a file from the drop folder to a live section page; the visibility rule that each rendering surface applies; and the integrity guard that protects the registry CSV against a malformed manual edit. It does not cover document authoring format (governed by the BPGP standard), the skin and design system, or the document viewer rendering engine. 1.3 RELATION TO THE CODE Every rule in this document is implemented in PHP under the live root C:\MAMP\htdocs\darmaster\. Where a rule names a function or a file, that name is exact and is the place to change the rule. The inline comments in those files restate each rule at the point of use; this document is the bird's-eye reference that ties them together. ================================================================================ 2. REGISTRY, THE SINGLE SOURCE OF TRUTH ================================================================================ 2.1 THE CSV AND ITS EDITOR The document registry is a single comma-separated file at __darmaster\api\doc_status.csv. It is the system of record for every document's publish status and classification. The editor user interface for the registry is __darmaster\08\fable5_doclib.php, labelled "Doc Registry" in the platform, which shows every registered row at every status and is the master control point: it can publish or unpublish any document. The registry mints a stable identifier per document (DARX-DOC-NNNN) on first registration and never changes or reuses it. 2.2 CLASSIFICATION COLUMNS Three columns drive visibility. The status column records the publish state. The entities column records every legal entity the document belongs to. The sections column records every section page the document belongs to. Each rendering surface reads these columns directly from the CSV; no surface reads the filename prefix to decide entity, and no surface keeps its own copy of the classification. 2.3 THE MULTI-VALUE ENTITIES COLUMN The entities column is multi-value: it holds a semicolon-joined list of entity codes, for example "DARX;DARH;DARM". A document with several entities belongs to each of them and appears in each of their libraries. The literal value "shared" matches every entity. The special scope DARMASTER is an aggregate that matches every entity, so the master views show documents across the whole platform. When the entities column is blank the platform falls back to the singular scanned entity, and then to the filename prefix, in that order. ================================================================================ 3. PUBLISH PIPELINE, DROP TO LIVE ================================================================================ 3.1 THE FOUR STEPS A new document becomes visible through four steps, each a deliberate operator action after the first: Step Action Result ──── ───────────────────────────── ───────────────────────────────────── 1 Drop the .txt or .html file File exists on disk; not yet in the in 11\0101\txt\ or registry. 11\0102\html\ 2 Open the Doc Registry The registry auto-scans the folders and registers the new file (status defaults to unpublished). 3 Assign one or more entities The document now appears in each to the document assigned entity's document library. 4 Assign a section and set The document now appears on that status to live entity's section page. 3.2 STATUS LIFECYCLE IN PRACTICE A freshly registered document is unpublished. It is visible in the entity library (the management view) as soon as an entity is assigned, but it does not reach a public section page until its status is live. Setting status to live is the publish gate. Setting status to archived removes the document from every surface except the Doc Registry itself. The registry retains master control: changing a live document back to any non-live status unpublishes it from the section pages immediately. ================================================================================ 4. VISIBILITY RULES, ONE PER SURFACE ================================================================================ 4.1 THE RULE TABLE Each rendering surface applies exactly one rule, implemented in exactly one function. The rules are: Surface Function (file) Rule ────────────────── ───────────────────────────── ────────────────────── Section pages (56) darx_row_matches entity assigned AND (render_portal.php) section assigned AND status is live Entity library (8) the filter in entity assigned AND index.php status is not archived Doc Registry fable5_doclib.php all rows, all statuses Sitemap section mui_docs_for entity AND section AND counts (darmaster_ui.php) status is live Homepage entity mui_total status is live tile count (darmaster_ui.php) The fifty-six section pages are the eight entity sites times the seven content sections; all of them are identical thin shims that defer to render_portal.php, so the single rule in darx_row_matches governs every one of them. The eight document libraries are the eight entity sites; all of them defer to the shared __darmaster\08\index.php, so its single filter governs every one of them. 4.2 SINGLE-SOURCE DISCIPLINE A visibility rule is changed in its one function only. It is never changed by editing a section page, a library shim, or a per-entity copy, because no such per-surface copy exists. This is the discipline that keeps all fifty-six section pages and all eight libraries behaving identically without per-page maintenance. 4.3 ENTITY-SCOPE NORMALIZATION A single-entity library shows only its own entity. Because a document may carry a foreign filename prefix while being assigned to this entity (for example a DARX-prefixed file shared to DARM), the library re-stamps every visible document to the library's own entity before grouping, so the document appears under the one correct entity band and never produces a stray foreign band. The per-document entity chip still reads the registry entities column, so the true multi-entity assignment remains visible on the card. The DARMASTER aggregate is exempt: it groups each document under its primary entity so a shared document lists exactly once. ================================================================================ 5. INTEGRITY GUARD, THE REGISTRY CSV ================================================================================ 5.1 THE FAILURE IT PREVENTS The registry is a single CSV. A malformed manual edit, in particular an unbalanced double quote, makes the comma-separated parser swallow the lines that follow it, so rows silently vanish from every read. Without protection this breaks every page at once and, worse, a subsequent write would persist the truncated file and lose the swallowed rows permanently. The guard removes both risks. 5.2 THE HIGH-WATER MARKER Every successful write records the number of rows it produced into a sidecar file, __darmaster\api\doc_status_rowcount.txt. A healthy registry never has fewer rows than its last write produced. This recorded count is the high-water mark against which both reads and writes are checked. The marker reads zero when absent, which disables the check, so the guard is inert and safe until the first write establishes a baseline. 5.3 READ RECOVERY AND WRITE REFUSAL On read, if the live file parses to fewer rows than the high-water mark, the platform serves the newest intact snapshot from __darmaster\api\_backups\ instead of the broken file, so every page keeps rendering the last good data. The event is logged and is never fatal. On write, every writer passes through one gated open function; if the live file has lost rows, the write is refused with an actionable message rather than truncating over the good data. Reads and writes resume automatically once the CSV is repaired or a backup is restored. The behaviour is verified by an automated test covering clean operation, corruption detection, recovery, write refusal, and resumption after repair. ================================================================================ 6. SCAN GATING, COST CONTROL ================================================================================ 6.1 THE FOLDER SIGNATURE A full folder scan reads every document's content to extract titles and previews, which is wasteful when nothing has changed. The platform computes a cheap signature of both document folders from each file's name, modified time, and size, using directory listing and file metadata only, with no content read. The signature changes whenever a document is added, removed, renamed, or edited in place. 6.2 WHEN A SCAN RUNS The Doc Registry runs its full scan-and-register only when the folder signature differs from the last recorded signature, or when the operator presses the Import button. The signature is stored in __darmaster\api\doc_scan_sig.txt. The document library still scans on every load because it draws its rendered cards directly from the files on disk, including the entity-specific viewer links; that scan is left in place because it is the library's data source, and at the current scale its cost is imperceptible. Revisit the library scan only if the library passes roughly one thousand documents. ================================================================================ 7. AI PROMPTS ================================================================================ This section is mandatory under the BPGP standard. The prompt below regenerates this document from the live platform code. ================================================================================ START OF PROMPT ================================================================================ You are documenting the Daralbeida internal platform under the live root [LIVE_ROOT]. Produce a BPGP v3.1 plain-text reference titled "Document Publish Pipeline and Visibility Contract" that records, from the code, how a document becomes visible on the platform. Cover, in this order: 1. The registry CSV at __darmaster\api\doc_status.csv as the single source of truth, its editor __darmaster\08\fable5_doclib.php, and the three classification columns entities, sections, and status. 2. The four-step publish pipeline: drop file; open registry to auto- register; assign entity to reach the library; assign section and set status live to reach the section page. 3. The per-surface visibility rules, one function each: darx_row_matches in render_portal.php (section pages, live only); the filter in __darmaster\08\index.php (library, not archived); fable5_doclib.php (all statuses); mui_docs_for and mui_total in darmaster_ui.php. 4. The registry integrity guard in api\modules\doc_status_lib.php: the row-count high-water marker, read recovery from api\_backups\, and write refusal on a row-lost file. 5. The stat-only folder signature that gates the registry scan. Verify every function and path against the code before stating it. Follow the highest-timestamp DARH_STDS_BPGP_* standard for format. Mark editable tokens with [SQUARE_BRACKETS]. ================================================================================ END OF PROMPT ================================================================================ ================================================================================ 8. REVISION HISTORY ================================================================================ Version Date Author Note ─────── ────────── ─────────────── ───────────────────────────────── 1.0 2026-06-16 Claude / PYB Initial issue. Records the publish pipeline, the five per-surface visibility rules, the registry integrity guard, and scan gating as implemented on 2026-06-16 UTC. ================================================================================ 9. ACRONYMS ================================================================================ CSV Comma-Separated Values DARH Daralbeida Holdings LLC DARM Daralbeida Maroc SARL DARX Daralbeida Brands LLC HTML HyperText Markup Language PHP PHP Hypertext Preprocessor TXT Plain-text file extension UID Unique Identifier UTC Coordinated Universal Time ================================================================================ 10. GLOSSARY ================================================================================ Aggregate Scope — The DARMASTER scope, which matches every entity so the master views show documents across the whole platform. Defined in Section 2.3. Archived — The single status that removes a document from every rendering surface except the Doc Registry itself. Defined in Section 3.2. Entities Column — The multi-value registry column holding a semicolon- joined list of entity codes; a document belongs to each entity listed. Defined in Section 2.3. Entity-Scope Normalization — The library behaviour of re-stamping every visible document to the library's own entity before grouping, so a foreign- prefixed shared document appears under the correct band. Defined in Section 4.3. High-Water Marker — The sidecar file recording the row count of the last successful registry write, used to detect a registry that has lost rows. Defined in Section 5.2. Live — The publish status that makes a document visible on a public section page; the publish gate. Defined in Section 3.2. Publish Gate — The requirement that a document's status be live before it appears on a section page. Defined in Section 3.2. Registry — The document classification system of record, the CSV at __darmaster\api\doc_status.csv. Defined in Section 2.1. Section Page — One of the fifty-six entity content pages, rendered by render_portal.php, that lists the live documents assigned to its entity and section. Defined in Section 4.1. Shared — The literal entities value that matches every entity. Defined in Section 2.3. -------------------------------------------------------------------------------- DOCUMENT CONTROL (FOOTER) -------------------------------------------------------------------------------- Document ID : DARX_TECH_SPEC_001 Version : 1.0 Status : IN_REVIEW Last Revised : 2026-06-16 03:08 UTC Update Cycle : 90 days Next Review Due : 2026-09-14 Annual Review : 2027-06-16 Owner : PYB / Daralbeida Distribution : Internal; principals, contractors, and AI systems working on the Daralbeida platform document system. Review Triggers : Any change to a visibility rule or its function; any new rendering surface that lists documents; any change to the registry schema or integrity guard; any change to the publish pipeline steps; annual review on the Annual Review date. COMPLIANCE : Each visibility rule lives in exactly one function (Section 4.1); change a rule there, never by editing a section page or a library copy. doc_status.csv must never be hand-edited in a way that drops rows; the integrity guard refuses writes against a row-lost file and recovery depends on the api\_backups\ snapshots, which must not be deleted wholesale. Revision History: See Section 8 -------------------------------------------------------------------------------- END OF DOCUMENT