acquaint.edit

Changing the store: create an entity, append an observation, rename with relinking, forget with a tombstone.

The hot path is append-only. append_observation() never edits an entry file, a writing card or a rule: it appends a dated, sourced entry to log/YYYY-MM.md (or a handle to identities.yaml). The one change it makes to an existing entry is making an inactive handle active again, and only when asked (reactivate). identities.yaml is rewritten whenever it changes, so comments in it are not kept. Turning observations into profile lines is a separate, reviewed pass.

These functions take exact references (ada-lovelace, person:ada-lovelace, people/ada-lovelace); matching names to ids is the caller’s job (acquaint.lookup.find_entity()), so nothing here acts on a guess.

Module Attributes

OBSERVATION_KINDS

What remember can record.

Functions

append_observation(store, ref, text, *[, ...])	Append one dated, sourced entry to the entity's log/YYYY-MM.md (and, for identity, to identities.yaml).
forget_entity(store, ref, *[, confirm, today])	Remove an entity's whole folder, hidden files included, after writing a salted tombstone.
new_entity(store, kind, name, *[, ...])	Scaffold <kind dir>/<slug>/PROFILE.md from the template for its kind, and seed POLICY.md.
rename_entity(store, ref, to, *[, today])	Give an entity a new id (to is a slug) or a new name and id (to is a name); links elsewhere follow.
tombstone_problem(store)	Why _tombstones.yaml cannot be trusted, or None.
tombstoned(store, *identifiers)	The tombstone matching any of these identifiers, if such an entity was forgotten.

acquaint.edit.OBSERVATION_KINDS = ('observation', 'interaction', 'identity', 'preference', 'view', 'rule')

What remember can record. The last three need a source at write time.

acquaint.edit.append_observation(store, ref, text, *, source=None, kind='observation', reactivate=False, disclosed=(), today=None)

Append one dated, sourced entry to the entity’s log/YYYY-MM.md (and, for identity, to identities.yaml).

An identity equal to an inactive one is refused, naming that entry, unless reactivate is set (see _append_identity()). disclosed (interaction only) lists the records the message identified, by exact id or reference, written as references (project:heron); never the text. A refusal writes nothing.

Return type:

dict[str, Any]

acquaint.edit.forget_entity(store, ref, *, confirm=False, today=None)

Remove an entity’s whole folder, hidden files included, after writing a salted tombstone.

Without confirm it only reports what it would remove, and which other records still mention the entity (it does not edit them: other people’s logs are append-only). The tombstone is written first, so a removal that fails half way still stops the entity being re-created, and running forget again finishes the job.

Return type:

dict[str, Any]

acquaint.edit.new_entity(store, kind, name, *, qualifier=None, description=None, force=False, today=None)

Scaffold <kind dir>/<slug>/PROFILE.md from the template for its kind, and seed POLICY.md.

Return type:

dict[str, Any]

acquaint.edit.rename_entity(store, ref, to, *, today=None)

Give an entity a new id (to is a slug) or a new name and id (to is a name); links elsewhere follow.

Return type:

dict[str, Any]

acquaint.edit.tombstone_problem(store)

Why _tombstones.yaml cannot be trusted, or None. A broken file must never read as “nobody was forgotten”.

Return type:

str | None

acquaint.edit.tombstoned(store, *identifiers)

The tombstone matching any of these identifiers, if such an entity was forgotten. Raises if the tombstone file is broken.

Return type:

dict | None