IF Commons GitHub

Estate fleet documents

0005Active

0005-estate-fleet-documents · owner if · domain commons

Requirements

FR-001checkpassing

The physical layer of Estate MUST be the folder src/physical/, exported as @intellectual-frontiers/estate/physical; it MUST import the governance and logical layers of Estate by package name, core, crypto/sha256, grc, anyfs and anyfs-bridge only at the subpaths its row of the table of Kanon names, and it MUST do no input or output of its own: every byte it reads or writes goes through a store it is given.

Enforced (check): .github: cd commons/estate && bun run verify — suite/fleet-documents.test.ts

Proved by: estate/suite/fleet-documents.test.ts

Written in: estate/src/physical/documents.ts, estate/src/physical/mod.ts

Tests: passed: suite/fleet-documents.test.ts the physical layer does no input or output of its own: it imports no file, network or proc

FR-002checkpassing

An asset MUST be kept as one document that holds its identity, kind, state, where it came from and the owner of each capability it offers, and it MUST be read back through defineAsset: a stored asset that breaks a rule of the estate (an owner for a capability its state does not offer, or none for one it does) MUST be a finding, never an asset.

Enforced (check): .github: cd commons/estate && bun run verify — suite/fleet-documents.test.ts

Proved by: estate/suite/fleet-documents.test.ts

Written in: estate/src/physical/documents.ts

Tests: passed: suite/fleet-documents.test.ts an asset is kept as one document and read back as the same asset, and a stored asset that

FR-003checkpassing

Every document type MUST have a schema at a stated version, written with the field $version; a document written at a newer version than the code reads MUST be refused as newer-version and never read as the current one.

Enforced (check): .github: cd commons/estate && bun run verify — suite/fleet-documents.test.ts

Proved by: estate/suite/fleet-documents.test.ts

Written in: estate/src/physical/documents.ts

Tests: passed: suite/fleet-documents.test.ts each type of document is written at version 1 with its version field, and one written at a

FR-004checkpassing

The documents MUST be named by layouts: the assets, the declarations and the accepted risks at <folder>/<first character>/<asset>.json, an observation at observations/<asset>/<instant>.json named by the instant with its hyphens and colons left out so that the names sort as the instants do, a reference to evidence at evidence/<asset>/<digest>.json, and the manifest at fleet.json; the layout of every folder MUST give back the key of every path it makes.

Enforced (check): .github: cd commons/estate && bun run verify — suite/fleet-documents.test.ts

Proved by: estate/suite/fleet-documents.test.ts

Written in: estate/src/physical/documents.ts

Tests: passed: suite/fleet-documents.test.ts the layouts name the documents: the shard is the first character, an observation is named

FR-005checkpassing

An identity that names a folder or a file MUST be made by parseAssetId before any path is made of it, so that an identity with a slash, a dot-dot, a space or a control character is refused as a value and no path leaves its folder.

Enforced (check): .github: cd commons/estate && bun run verify — suite/fleet-documents.test.ts

Proved by: estate/suite/fleet-documents.test.ts

Written in: estate/src/physical/documents.ts

Tests: passed: suite/fleet-documents.test.ts a document too deep to be read back is refused when it is written, a large one is kept who; passed: suite/fleet-documents.test.ts an identity that is a path, a dot-dot, a space or a control character is refused as a valu

FR-006checkpassing

An observation MUST carry the asset, a UTC instant that the calendar has, the source it is attributed to and the keyed records seen; an observation with no source MUST be refused (no evidence without attribution), and the results of the policies it carries MUST each name a status and the controls they give evidence for.

Enforced (check): .github: cd commons/estate && bun run verify — suite/fleet-documents.test.ts

Proved by: estate/suite/fleet-documents.test.ts

Written in: estate/src/physical/documents.ts

Tests: passed: suite/fleet-documents.test.ts a document too deep to be read back is refused when it is written, a large one is kept who; passed: suite/fleet-documents.test.ts an observation names a source and a calendar instant and carries its results; one with no

FR-007checkpassing

A reference to evidence MUST hold the digest of the evidence (64 hexadecimal digits), the store it is kept in, the asset it is about, its type and the instant it was observed, and it MUST NOT hold the bytes, which stay in the evidence stores of grc; the manifest MUST hold the name of the fleet, the schema and the layout it is kept at, and the instant it was made.

Enforced (check): .github: cd commons/estate && bun run verify — suite/fleet-documents.test.ts

Proved by: estate/suite/fleet-documents.test.ts

Written in: estate/src/physical/documents.ts

Tests: passed: suite/fleet-documents.test.ts a reference to evidence holds the digest, the store, the subject and the type and never th

Acceptance scenarios

  1. Given each type of document, When it is written and read, Then the same value comes back, per FR-002, FR-006 and FR-007.
  2. Given a stored asset that offers a capability with no owner, When the assets are listed, Then it is a finding and not an asset, per FR-002.
  3. Given a document written at version 9, When it is read, Then it is refused as a newer version, per FR-003.
  4. Given the identity ../../etc/passwd, When a document is asked for, Then it is refused before any path is made, per FR-005.
  5. Given an observation with no source, When it is recorded, Then it is refused, per FR-006.

Out of scope

  • The bytes of evidence and the stores that keep them: grc's.
  • Signing a document or a manifest: the interface is designed, the signer is later.

Edge cases

  • A file in a folder that no layout of the folder names is a finding of the folder, per FR-004.
  • An asset identity of one character has a place, because the shard is the first character, and one of a hundred characters is a document name; one longer is refused by parseAssetId, per FR-005.

Assumptions

  • A document name is at most 128 characters of letters, digits and . _ ~ @ + = -, as AnyFS's documents are.

Open questions

  • None.

Key entities

  • Document - one typed record of the estate in a store, with a schema, a layout and a revision.
  • Manifest - what a store says it is: the fleet, the schema and the layout it is kept at.

Success criteria

SC-001success criterion

A document that breaks a rule of the estate, or that no layout names, never becomes a value of the estate: it is a finding.

Review & acceptance checklist

  • [x] Every requirement is testable (MUST / MUST NOT), not aspirational
  • [x] No company fact is asserted here
  • [x] Every open item is marked, not silently decided

Cited by

Estate, physical/documents

Titles, headings, exports, tables, columns and requirements. Esc closes.