cmd/taisce/commands.go
cmd/taisce · 657 lines · 15 declarations · source
Declarations
const usage
41 lines of declaration
const usage = `taisce — memory for agents
taisce serve serve memory over HTTP and form the backlog (default)
taisce bootstrap create the schema, run every migration, and mint the first credentials
taisce project create <name> create a project and its partition
taisce project list list the projects that exist
taisce project suspend <name> make a project's memory unreachable, reversibly
taisce project resume <name> return a suspended project to service
taisce project retention <name> how long new turns are kept: a number of days, or indefinite
taisce credential issue <name> mint a credential (--project, --read-only); the token is shown once
taisce credential list list credentials (--project; without it, the operator credentials)
taisce credential revoke <id> stop a credential resolving
taisce operator issue <name> mint an operator credential for the management surface; shown once
taisce audit verify recompute the ledger's chain and report what it covers
taisce audit seal seal everything written since the last seal
taisce formation parked inspect a bounded page of parked turn metadata (--project required)
taisce formation unpark retry one parked turn (--project required, then the observation id)
taisce artifact limits inspect or replace project artifact storage allowances
taisce recover facts restore a bounded page of missing facts (--project required)
taisce recover chunks restore message chunks with stable IDs (--project required)
taisce rebuild facts reinterpret one source atomically (--project, --source, --key required)
taisce rebuild project run a resumable page of fact rebuilds (--project, --key required)
taisce rebuild status inspect a project rebuild (--project, --key required)
taisce rebuild cancel cancel a project rebuild (--project, --key required)
taisce rebuild reports write the reports a project is missing now (--project required)
taisce health show content-free operational aggregates using the operator connection
taisce ingest <file>... observe documents through the API as segments (--api, TAISCE_TOKEN)
taisce conformance run the adapter conformance suite against a deployment (--driver or --reference)
taisce embeddings <op> start, build, follow, status, activate, cancel, prune, repair or search message generations
taisce entity-embeddings <op> the same for entity candidate generations, without follow
taisce report-embeddings <op> the same for thematic report generations, without follow
taisce probe check local readiness (--live, --worker, --manage)
taisce version what this binary is (also --version)
taisce help [<command>] this list (also -h, --help); taisce <command> --help prints one command's lines
Configuration is read from the environment. TAISCE_MEMORY_DSN and TAISCE_REGISTRY_DSN are the two
database connections, and they are separate so that a memory query cannot read a credential.
TAISCE_SCHEMA optionally selects this instance's memory namespace (default: memory). With
TAISCE_MANAGE_API and TAISCE_OPERATOR_TOKEN set, project, credential, audit and formation speak the
management surface instead of the database.
`
func wantsHelp
func wantsHelp(args []string) bool
wantsHelp reports whether a command's arguments ask for help. An argument after "--" is a value, not a flag, so it does not count.
func commandHelp
func commandHelp(out io.Writer, command string) (bool, error)
commandHelp prints the usage lines of one command, and reports whether it has any.
func dispatch
func dispatch(ctx context.Context, log *slog.Logger, args []string) error
dispatch routes a subcommand, defaulting to serving.
Defaulting matters: the container's command is the common case, and a deployment that has to remember to say "serve" is one that fails at start with a usage message.
func bootstrap
func bootstrap(ctx context.Context, log *slog.Logger, args []string) error
bootstrap brings an empty database to a state that can serve.
It is idempotent, because the compose file and the chart both run it on every start and a bootstrap that fails the second time is a deployment that cannot restart. Every step underneath it is already idempotent — migrations record their version, provisioning uses IF NOT EXISTS, and the roles are created only when absent — so this is composition rather than new logic.
Why it mints a credential
A running instance nobody can authenticate to is a running instance nobody can use. The token is printed once, to stdout, and is not recoverable afterwards: only its digest is stored. That is the property being bought, so the message says it plainly rather than leaving an operator to discover it when they lose the value.
func credentialsForProject
func credentialsForProject(ctx context.Context, pool *pgxpool.Pool, project string) (int, error)
credentialsForProject counts the live credentials that grant a project.
This is the question bootstrap actually needs answered: not how many keys exist, but whether the project it just created can be reached by anyone.
func project
func project(ctx context.Context, args []string) error
project creates and lists projects.
Deleting one is deliberately absent until it can be done with the guarantees erasure already makes: dropping a partition would remove memory without a counted residual, which is the one thing this product promises never to do quietly.
func credentialCommand
func credentialCommand(ctx context.Context, args []string) error
credentialCommand mints and revokes credentials.
func retentionSaid
func retentionSaid(days *int) string
retentionSaid says a policy the way the operator wrote it.
func requireActiveProject
func requireActiveProject(ctx context.Context, admin *pgxpool.Pool, project string) error
requireActiveProject is requireProject for minting: a project that exists but is suspended is refused too, because a credential for it would authenticate and reach nothing.
func requireProject
func requireProject(ctx context.Context, admin *pgxpool.Pool, project string) error
requireProject refuses to mint a credential for a project that does not exist.
This is the check a foreign key would make, in the only place that can make it: the credential is in the control namespace and the project is in the memory namespace. This preflight keeps operator mistakes explicit; it is not a claim that PostgreSQL forbids cross-schema foreign keys.
It is a weaker guarantee than a constraint — a credential minted some other way could still name nothing — and it catches the case that actually happens, which is a typo becoming a token that authenticates successfully and reaches no memory at all.
func adminPool
func adminPool(ctx context.Context) (*pgxpool.Pool, pg.Schema, error)
adminPool connects with the identity that may change the schema.
The operator commands run DDL and touch the registry, which the serving identities deliberately cannot do. They are a different connection for that reason, and the separation is the same one the server relies on rather than a second mechanism.
func auditCommand
func auditCommand(ctx context.Context, args []string) error
auditCommand is the operator's own check on their own ledger.
Theirs rather than ours, and that is the whole point of the narrowed design: the earlier plan was a signed checkpoint a CLIENT verified, which existed so a customer could catch a vendor. Self-hosted there is no vendor — the operator holds the disk — and what remains is an operator demonstrating to their own auditor that they have not rewritten their own records.
func printSeal
func printSeal(seal domain.AuditSeal)
printSeal and reportVerification are the audit command's output, whichever path it took.
One function for both paths, because the promise is that a script written against one keeps working against the other — and the first time that promise was only a comment, the management path printed raw JSON and exited 0 over a ledger that did not verify.
func reportVerification
func reportVerification(v domain.AuditVerification) error
reportVerification prints what the check found and fails the command when the ledger does not verify: non-zero, because this is the one command whose result something should act on.