114 lines
4.5 KiB
Markdown
114 lines
4.5 KiB
Markdown
|
# ENC-ASL-CORE-INDEX ADDENDUM: Federation Encoding
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 1. Purpose
|
||
|
|
|
||
|
|
This addendum defines **on-disk encoding changes** required to support the **Federation Specification**:
|
||
|
|
|
||
|
|
* Domain identifiers for artifacts and index entries
|
||
|
|
* Visibility flags for internal vs published state
|
||
|
|
* Backward-compatible update to existing index records
|
||
|
|
* Integration with existing block, segment, and tombstone layouts
|
||
|
|
|
||
|
|
It ensures **deterministic reconstruction** across domains while preserving index lookup semantics.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 2. New Fields for Index Records
|
||
|
|
|
||
|
|
Each **ArtifactIndexRecord** is extended to include **federation metadata**:
|
||
|
|
|
||
|
|
| Field | Type | Description |
|
||
|
|
| ------------------- | ------------------------ | --------------------------------------------------------------------------------------------------- |
|
||
|
|
| `DomainID` | uint32 / opaque | Unique domain identifier for the artifact. Must match the domain in which the artifact was created. |
|
||
|
|
| `Visibility` | uint8 (enum) | Visibility status of the artifact: `0 = internal`, `1 = published`. |
|
||
|
|
| `CrossDomainSource` | optional uint32 / opaque | DomainID of original domain if the artifact is imported from another domain; `NULL` if local. |
|
||
|
|
|
||
|
|
**Encoding Notes:**
|
||
|
|
|
||
|
|
* `DomainID` and `Visibility` are **always present** in index records, even for legacy artifacts (legacy default: internal, local domain).
|
||
|
|
* `CrossDomainSource` is **optional**; present only for imported artifacts.
|
||
|
|
* Existing `(BlockID, offset, length)` mapping is unchanged.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 3. Segment Header Updates
|
||
|
|
|
||
|
|
Each segment now includes:
|
||
|
|
|
||
|
|
* `SegmentDomainID` (uint32 / opaque): domain owning this segment
|
||
|
|
* `SegmentVisibility` (uint8): maximum visibility of all artifacts in the segment (`internal` or `published`)
|
||
|
|
* Optional: `FederationVersion` (uint8) to allow backward-compatible upgrades
|
||
|
|
|
||
|
|
This allows **fast filtering** of visible segments during lookup in federated domains.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 4. Tombstone Encoding
|
||
|
|
|
||
|
|
* Tombstones include `DomainID` and `Visibility` fields to ensure **deterministic shadowing** across domains.
|
||
|
|
* Shadowing rules:
|
||
|
|
|
||
|
|
* A tombstone in domain A only shadows artifacts in domain A.
|
||
|
|
* Published artifacts cannot be accidentally shadowed by internal artifacts from another domain.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 5. Block Records
|
||
|
|
|
||
|
|
No change to `(BlockID, offset, length)` itself; however:
|
||
|
|
|
||
|
|
* Blocks supporting **published artifacts** are considered **cross-domain safe**.
|
||
|
|
* Optional **DomainID metadata** may be stored with blocks to speed up GC and federation operations.
|
||
|
|
* Addressing and segment packing rules are unchanged.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 6. Lookup and Reconstruction Rules
|
||
|
|
|
||
|
|
* When reconstructing **CURRENT in a domain**:
|
||
|
|
|
||
|
|
1. Filter segments and records by `DomainID` and `Visibility`.
|
||
|
|
2. Include artifacts with `DomainID = local` or `Visibility = published`.
|
||
|
|
3. Include imported artifacts by following `CrossDomainSource`.
|
||
|
|
4. Apply standard shadowing and tombstone rules per domain.
|
||
|
|
|
||
|
|
* Determinism and immutability guarantees remain identical to single-domain ENC-ASL-CORE-INDEX.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 7. Backward Compatibility
|
||
|
|
|
||
|
|
* Legacy segments without federation fields are treated as:
|
||
|
|
|
||
|
|
* `DomainID = local domain`
|
||
|
|
* `Visibility = internal`
|
||
|
|
* Lookup semantics automatically ignore artifacts from other domains until explicitly migrated.
|
||
|
|
* Federation fields are **forward-compatible**; versioning in segment headers allows safe upgrades.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 8. Normative Invariants
|
||
|
|
|
||
|
|
1. **DomainID presence:** Every index record must include a `DomainID`.
|
||
|
|
2. **Visibility correctness:** Published artifacts are always visible to other domains; internal artifacts are not.
|
||
|
|
3. **CrossDomainSource integrity:** Imported artifacts retain immutable reference to original domain.
|
||
|
|
4. **Deterministic encoding:** Serialization of index records and segments must be identical across platforms for the same snapshot + log.
|
||
|
|
5. **Backward compatibility:** Legacy records are interpreted safely with default federation metadata.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 9. Summary
|
||
|
|
|
||
|
|
This addendum updates **ENC-ASL-CORE-INDEX** to support **federation**:
|
||
|
|
|
||
|
|
* Adds `DomainID`, `Visibility`, and optional `CrossDomainSource` to index records
|
||
|
|
* Updates segment headers for fast domain/visibility filtering
|
||
|
|
* Ensures deterministic lookup, reconstruction, and shadowing rules per domain
|
||
|
|
* Maintains backward compatibility with legacy segments
|
||
|
|
|
||
|
|
It integrates federation metadata **without altering the underlying block or artifact encoding**, preserving deterministic execution and PEL provenance.
|
||
|
|
|
||
|
|
|