Directory artifact

Type: types/definition.md

A directory artifact is a directory whose root holds a manifest, ARTIFACT.yaml, whose type field names a directory type. The directory is one validation unit, as a single typed file is. Its members are the direct Markdown children that match a role of the type's layout.

A directory type is a type spec whose frontmatter carries a layout. The layout declares the roles an instance has: for each, the file at the directory root that fills it, the document type expected there, the roles whose fields it repeats and must equal (identity), the roles whose declarations its references resolve against (cites) and the roles whose acceptance its verdict settles (verifies). It also declares which roles every instance has and which a discriminating field adds, and whether a file matching no role is a finding (membership: closed) or admitted (membership: open). A role is a position the type declares; the file that fills it is a member; a role's name is the same whatever file fills it. A role's cites bounds where its references may resolve: it does not require the role to cite each listed role, and it is not a list of what the role's author reads.

The manifest selects the type and may pin members: an entry under members maps a filename to a digest that its bytes must match. Whether every member must be pinned is the type's rule, not the layout's. A type may require further manifest metadata through its schema, which constrains the manifest only.

A working instance is a directory artifact whose manifest names only its type. It is recognised from its first member; validation reports its absent required members and checks the relations its present members reach, and a candidate for a role can be validated in that role without being written. A finished instance is one whose manifest pins what the type requires; what makes it frozen is the collection's rule for the area it is retained in.

Boundaries

• A directory of typed files with no manifest is not a directory artifact; its files validate one by one and no relation between them is checked.
• Nested members are not declared: every role is a direct child. A directory artifact inside another is composition, which the layout vocabulary does not describe.
• A directory type's layout owns membership and relations. The type's schema owns the manifest's metadata. A type rule computes what needs a grammar, such as record declarations and references. Nothing else about the directory's structure is declared anywhere.
• The analysis workflow runs a method's roles against a typed directory artifact and takes their relations from the layout; a role, a relation and a member mean here what they mean there (ADR 118).

The exact checks are in the validation contract; the decisions are ADR 095, ADR 111 and ADR 114. The first directory type is the analysis set.