scribe

Documentation

Overview

Package scribe builds the ledger scribe's context and ingests what the scribe returns (itd-2609020625402599, spc-2609020626045177).

The scribe (agents/scribe.md) transcribes a returned reading's records and the researcher's dispositions into the ledger's declared shapes, and its access rule is the reading assembler's exact inverse: ledger content only, never the shipped repository. Until this package that rule was held by the definition alone. Here it is held by construction, on the reading assembler's idiom:

• Assemble builds the context by POSITIVE inclusion at directory grain, from an allow list derived from the ledger's own directory constants (issueschema.LedgerDirs), plus the researcher's supplied text. Nothing outside the list is walked, and assertAllowList refuses any item whose path is outside it whatever route it arrived by. A manifest names every path passed, by hash, and is parked in the local tier.
• Ingest validates the scribe's four outputs and writes dispositions, admissions and surprises through the capture verbs' own functions, adding no validation path of its own beyond the one thing only it can check: that the scribe authored nothing. Every ground, exit condition and surprise the payload carries must already stand in the supplied text. The manifest is promoted beside the run last, inside the read block.

Both artefacts carry the per-run context stamp (core/sessionkind), so a retained transcript that held this context says so, and the transcript store's separation check can see it (adr-2609021016275803).

`scribe` is its own top-level verb rather than a sub-verb of `reading`, because the two contexts must never share a front door.

Index

• Constants
• Variables
• func AllowList() []string
• type AssembleRequest
• type AssembleResult
  • func Assemble(req AssembleRequest) (AssembleResult, error)
• type Context
• type Exclusion
• type FidelityFlag
• type IngestRequest
• type IngestResult
  • func Ingest(req IngestRequest) (IngestResult, error)
  • func (r IngestResult) Landed() []string
• type LedgerEntry
• type Manifest
• type ManifestItem
• type OutAdmission
• type OutDisposition
• type OutSurprise
• type Output
• type Refusal
• type Supplied
• type SuppliedHashes

Constants

const (
	ContextType  = "abcd.scribe.context/1"
	ManifestType = "abcd.scribe.manifest/1"
	OutputType   = "abcd.scribe.output/1"
)

The three artefact type tags. They are carried in the documents so a loose file can be told apart without its name.

const (
	ContextFileName  = "context.json"
	ManifestFileName = "scribe-manifest.json"
)

The parked filenames. ManifestFileName is also the name the manifest is promoted under beside the run.

const DefaultRunDir = ".abcd/.work.local/scratch/scribe-runs"

DefaultRunDir is the local-tier directory a session's context and manifest are parked in, one subdirectory per reading run. The local tier is on the reading assembler's exclusion floor, so nothing parked here reaches a reading.

const DefinitionPath = "agents/scribe.md"

DefinitionPath is the scribe definition whose hash the manifest records.

const SchemaVersion = 1

SchemaVersion is the shape version of the context and the manifest.

Variables

var ErrSymlink = errors.New("scribe: a symlink inside the ledger")

ErrSymlink refuses a symlinked directory or leaf inside the allow list: a link is a route out of the ledger that a prefix check on its name cannot see.

Functions

func AllowList

func AllowList() []string

AllowList is every directory the scribe's context may draw from, repository relative: the issue ledger's own directory list under its root. It is DERIVED from issueschema.LedgerDirs, so a family the ledger declares later is on this list the day its constant is, and the reading assembler's comparative exclusion rows describe the same set from the same function.

Types

type AssembleRequest

type AssembleRequest struct {
	RepoRoot string
	// Run is the ingested reading run the session transcribes for (rdg-N).
	Run string
	// DispositionsPath is the researcher's dispositions text, in whatever form
	// they wrote it. It is the one supplied path, and it is read, never walked.
	DispositionsPath string
	// OutDir is where the context and the manifest go; empty means the local-tier
	// default for the run. OutDirLabel is the operator's spelling of it, for
	// refusals.
	OutDir      string
	OutDirLabel string
	// DryRun writes nothing unless OutDir names somewhere to write.
	DryRun bool
}

AssembleRequest is one scribe assembly: the run, the researcher's supplied dispositions, and where the two artefacts go.

type AssembleResult

type AssembleResult struct {
	Run           string   `json:"run"`
	ContextStamp  string   `json:"context_stamp"`
	ContextSHA256 string   `json:"context_sha256"`
	ItemCount     int      `json:"item_count"`
	AllowList     []string `json:"allow_list"`
	OutDir        string   `json:"out_dir,omitempty"`
	Artefacts     []string `json:"artefacts"`
	Written       bool     `json:"written"`

	Context  Context  `json:"-"`
	Manifest Manifest `json:"-"`
}

AssembleResult is what one assembly produced. The two artefacts are carried for an in-memory caller and named by basename.

func Assemble

func Assemble(req AssembleRequest) (AssembleResult, error)

Assemble builds the scribe's context for one ingested run.

type Context

type Context struct {
	Type          string `json:"_type"`
	SchemaVersion int    `json:"schema_version"`
	// ContextStamp is the scribe kind's per-run stamp over the ledger array, in
	// the position the reading bundle carries its own.
	ContextStamp string        `json:"context_stamp"`
	Run          string        `json:"run"`
	Ledger       []LedgerEntry `json:"ledger"`
	Supplied     Supplied      `json:"supplied"`
}

Context is `abcd.scribe.context/1`: the scribe session's whole working set.

type Exclusion

type Exclusion struct {
	Source string `json:"source"`
	Signal string `json:"signal"`
}

Exclusion is one class of material the context refuses, and the signal that holds the refusal.

type FidelityFlag

type FidelityFlag struct {
	First  string `json:"first"`
	Second string `json:"second"`
}

FidelityFlag names two pieces of material that disagree, and stops there.

type IngestRequest

type IngestRequest struct {
	RepoRoot string
	// ScribeJSONPath is the payload the scribe returned.
	ScribeJSONPath string
	// ContextPath is the context the session was handed; empty means the local-
	// tier default for the payload's run. The manifest is read from beside it.
	ContextPath string
	// DispositionsPath is the researcher's dispositions text, the file assemble
	// was handed. It is required: the parked pair sits where a scribe session
	// with tools can rewrite it, so the verbatim checks read the researcher's
	// own file, and the parked copy and the manifest's hash are held to it.
	DispositionsPath string
}

IngestRequest is one scribe ingest.

type IngestResult

type IngestResult struct {
	Run           string                      `json:"run"`
	ContextSHA256 string                      `json:"context_sha256"`
	Dispositions  []capture.DispositionResult `json:"dispositions"`
	Admissions    []capture.AdmitResult       `json:"admissions"`
	Surprises     []capture.SurpriseResult    `json:"surprises"`
	Outstanding   []string                    `json:"outstanding"`
	// FidelityFlags and Refusals are carried to the researcher UNRESOLVED and
	// never into a record, which is what the definition promises.
	FidelityFlags []FidelityFlag `json:"fidelity_flags"`
	Refusals      []Refusal      `json:"refusals"`
	// Manifest is the promoted manifest's repository-relative path, set only
	// once every write has landed, and only when at least one record did.
	Manifest string `json:"manifest,omitempty"`
}

IngestResult is what one ingest landed and what it carries back unresolved.

func Ingest

func Ingest(req IngestRequest) (IngestResult, error)

Ingest validates one scribe payload and writes what it transcribed.

func (IngestResult) Landed

func (r IngestResult) Landed() []string

Landed names every record this ingest wrote, in order.

type LedgerEntry

type LedgerEntry struct {
	Path string `json:"path"`
	Text string `json:"text"`
}

LedgerEntry is one ledger record as the scribe receives it. The scribe files by ledger path, so its material may name one; it is the reading bundle that may not.

type Manifest

type Manifest struct {
	Type             string         `json:"_type"`
	SchemaVersion    int            `json:"schema_version"`
	ContextStamp     string         `json:"context_stamp"`
	Run              string         `json:"run"`
	DefinitionSHA256 string         `json:"definition_sha256"`
	ContextSHA256    string         `json:"context_sha256"`
	Supplied         SuppliedHashes `json:"supplied"`
	Items            []ManifestItem `json:"items"`
	AllowList        []string       `json:"allow_list"`
	Exclusions       []Exclusion    `json:"exclusions"`
}

Manifest is `abcd.scribe.manifest/1`: what the assembly passed, by path and hash, and what it refused. It carries no record text.

type ManifestItem

type ManifestItem struct {
	Path   string `json:"path"`
	Bytes  int    `json:"bytes"`
	SHA256 string `json:"sha256"`
}

ManifestItem names one ledger record passed, by path, length and hash.

type OutAdmission

type OutAdmission struct {
	Item    string `json:"item"`
	Grounds string `json:"grounds"`
}

OutAdmission is one admission the scribe transcribed.

type OutDisposition

type OutDisposition struct {
	Item          string   `json:"item"`
	State         string   `json:"state"`
	Grounds       string   `json:"grounds"`
	ExitCondition string   `json:"exit_condition"`
	Supersedes    string   `json:"supersedes"`
	Recurs        []string `json:"recurs"`
}

OutDisposition is one disposition the scribe transcribed.

type OutSurprise

type OutSurprise struct {
	OccasionedBy string `json:"occasioned_by"`
	Text         string `json:"text"`
}

OutSurprise is one surprise the scribe transcribed.

type Output

type Output struct {
	Type          string           `json:"_type"`
	Run           string           `json:"run"`
	ContextSHA256 string           `json:"context_sha256"`
	Dispositions  []OutDisposition `json:"dispositions"`
	Admissions    []OutAdmission   `json:"admissions"`
	Surprises     []OutSurprise    `json:"surprises"`
	FidelityFlags []FidelityFlag   `json:"fidelity_flags"`
	Outstanding   []string         `json:"outstanding"`
	Refusals      []Refusal        `json:"refusals"`
}

Output is `abcd.scribe.output/1`, the scribe's whole return.

type Refusal

type Refusal struct {
	Subject string `json:"subject"`
	Reason  string `json:"reason"`
}

Refusal is something the scribe refused, with its reason.

type Supplied

type Supplied struct {
	Dispositions string `json:"dispositions"`
}

Supplied is the researcher's own material, verbatim.

type SuppliedHashes

type SuppliedHashes struct {
	DispositionsSHA256 string `json:"dispositions_sha256"`
}

SuppliedHashes is the manifest's account of the supplied text.