tasks

func DefaultDBPath ¶

func DefaultDBPath() string

DefaultDBPath returns the conventional path for the unified pasture database, used by both the `pasture` CLI and the `pastured` daemon (PROPOSAL-2 §7.1).

Resolution order:

1. $PASTURE_DB_PATH
2. $XDG_DATA_HOME/pasture/pasture.db
3. $HOME/.local/share/pasture/pasture.db
4. .pasture/pasture.db (last-resort relative fallback when $HOME is unset)

The directory is NOT created here; the caller (typically OpenTaskTracker or OpenTracker) calls os.MkdirAll on filepath.Dir of the result before the file is opened for writing.

func DefaultNamespace ¶

func DefaultNamespace() (string, error)

DefaultNamespace returns the namespace URI that pasture uses when the user has not specified --namespace explicitly. It delegates to the Provenance namespace package so the same derivation rules apply across the toolkit.

func OpenAuditDBForFreeFloating ¶

func OpenAuditDBForFreeFloating(dbPath string) (*sql.DB, error)

OpenAuditDBForFreeFloating opens an auxiliary *sql.DB handle on the same pasture.db file that protocol.TaskTracker writes to, with the same WAL + busy_timeout=5000 pragmas openTaskTrackerImpl applies. It exists so callers outside internal/tasks (e.g. cmd/pastured wiring code, test code) can obtain a direct SQL handle for ad-hoc queries or pasture-specific table writes without depending on internal trackerImpl details.

Note: the free-floating recording helpers (RecordGitEvent / RecordSkillEvent / RecordSessionEvent) no longer require this handle internally — they now use tracker.RecordEventReturningId which bundles the write + id recovery. The handle is still accepted as a parameter by those helpers for API compatibility.

The returned handle MUST be closed by the caller; typically callers cache it for the lifetime of the daemon and Close it at shutdown.

dbPath: the SAME path used to open the TaskTracker. Empty string resolves to DefaultDBPath() (matching openTaskTrackerImpl's behaviour).

Errors are *pasterrors.StructuredError with CategoryConnection (file open failure) or CategoryStorage (PRAGMA failure).

This helper is a thin re-export of openAuditHandle so the rest of the tree (cmd/pastured, hooks/git_recorder.go) doesn't need access to package-private names.

func OpenTaskTracker ¶

func OpenTaskTracker(dbPath string) (protocol.TaskTracker, error)

OpenTaskTracker opens the unified pasture.db SQLite file at dbPath, runs the audit migrator, opens the Provenance tracker on the same file, and returns a wrapped protocol.TaskTracker.

dbPath: filesystem path to the unified database. Empty string resolves to DefaultDBPath (honours $PASTURE_DB_PATH and $XDG_DATA_HOME). Parent directories are created if they do not exist.

Errors are *pasterrors.StructuredError with category:

• CategoryConnection (exit 2): file/dir cannot be opened.
• CategoryStorage (exit 5): migration or DDL failure.
• CategoryValidation (exit 1): newer-schema rejection.

Callers MUST call Close on the returned tracker to release file handles.

This is the in-package entry point. External callers should use protocol.OpenTaskTracker, which is wired through init() above.

func OpenTracker ¶

func OpenTracker(dbPath string) (provenance.Tracker, error)

OpenTracker opens the Provenance tracker at dbPath, creating any missing parent directories along the way. An empty dbPath resolves to DefaultDBPath.

On failure the returned error is a *pasterrors.StructuredError with CategoryConnection, so callers can map it to exit code 2 via pasterrors.ExitCode.

func RecordGitEvent ¶

func RecordGitEvent(
	ctx context.Context,
	tracker protocol.TaskTracker,
	auditDB *sql.DB,
	sha string,
	eventType protocol.EventType,
	payload map[string]any,
) (int64, error)

RecordGitEvent records a free-floating git event (commit, push, rebase) to audit_events and attaches a ContextGit edge keyed by the supplied SHA / ref.

Parameters:

• ctx: context for cancellation; propagates to RecordEventReturningId and AttachContext.
• tracker: the unified TaskTracker (typically obtained from OpenTaskTracker). MUST be non-nil.
• auditDB: retained for API compatibility with existing callers; no longer used by the implementation (RecordEventReturningId bundles write + id recovery atomically, removing the need for a separate SELECT MAX round-trip). MAY be nil without causing a validation error.
• sha: the git commit SHA (or remote ref for pushes / base-ref for rebases). Used as the context_id of the ContextGit edge. MUST be non-empty; an empty sha would create a row no Timeline lookup can match.
• eventType: usually one of EventGitCommit / EventGitPush / EventGitRebase above; callers MAY pass any non-empty string per §7.3 / §7.5 open-string convention.
• payload: free-form key/value pairs. Should include {"sha": sha} for symmetry with the context edge; not enforced.

The recorded AuditEvent's Role field is set to DefaultGitRole — the canonical hook-handler name from PROPOSAL-2 §7.7.2's "pasture/automaton/hook/<name>" pattern. S3's audit-side legacy-role shim resolves this to an agent_id; post-S8 the workflow boundary will supply agent_id directly.

On success returns the int64 audit_events.id of the newly-inserted row so callers can attach further contexts (e.g., a post-epoch commit citing epoch X also gets ContextEpoch — see §11 Scenario 7 multi-context attachment).

Errors are *pasterrors.StructuredError with one of:

• CategoryValidation: nil tracker, empty sha, or an empty eventType (the underlying audit store would silently accept these but they're programming errors here).
• CategoryStorage: RecordEventReturningId / AttachContext write failure (file unwritable, schema drift, etc.). Underlying error wrapped via pasterrors.StructuredError.Why.

func RecordSessionEvent ¶

func RecordSessionEvent(
	ctx context.Context,
	tracker protocol.TaskTracker,
	auditDB *sql.DB,
	sessionId string,
	eventType protocol.EventType,
	payload map[string]any,
) (int64, error)

RecordSessionEvent records a free-floating Claude Code session event to audit_events and attaches a ContextSession edge keyed by the supplied session id.

See RecordGitEvent for the parameter / error contract; only the context kind (ContextSession) and the suggested EventType (EventSessionRecorded) differ.

Note: pasture also has a separate session_entries table (R6 — sub-PROV-O granularity for ACP SessionUpdate streams) reached via tracker.RecordSessionEntries; that path is for storing the streamed session content. RecordSessionEvent here records the higher-level "a session happened" event so it shows up in the audit timeline alongside epoch transitions and git events.

func RecordSkillEvent ¶

func RecordSkillEvent(
	ctx context.Context,
	tracker protocol.TaskTracker,
	auditDB *sql.DB,
	skillRunId string,
	eventType protocol.EventType,
	payload map[string]any,
) (int64, error)

RecordSkillEvent records a free-floating skill-invocation event to audit_events and attaches a ContextSkill edge keyed by the supplied skill run id (e.g., "pasture:user-elicit-<run-id>").

See RecordGitEvent for the parameter / error contract; only the context kind (ContextSkill) and the suggested EventType (EventSkillInvoked) differ.

`skillRunId` is the canonical id of the skill invocation. Per PROPOSAL-2 §7.3 example: "pasture:user-elicit-<run-id>" — the wire string is whatever the caller wants to use for Timeline lookups via `pasture task events --context-kind=SkillContext --context-id=<run-id>`.

func RegisterWellKnownAgents ¶

func RegisterWellKnownAgents(ctx context.Context, tracker protocol.TaskTracker, cache *WellKnownAgentCache) error

RegisterWellKnownAgents mints (or recovers) every entry in WellKnownAgents() against the supplied tracker and populates cache.

Idempotency contract (Scenario 14): two consecutive calls against the same underlying database produce identical row counts in `agents`, `agents_software`, `pasture_well_known_agents`, and `pasture_agent_categories`, AND identical AgentIDs in `pasture_well_known_agents` (pointwise across startups).

tracker MUST implement auditDBHolder (i.e. it must expose an audit *sql.DB handle via auditDBHandle). Both the production *trackerImpl and any test fake that wires up a real *sql.DB satisfy this. Callers that pass a tracker without the method get a CategoryConfig *StructuredError pointing at the wiring error.

cache MUST be non-nil. After successful return, cache contains exactly WellKnownAgentCount entries; on any error, cache may contain a strict subset (entries up to and including the failure point are populated; later entries are not). Partial population is safe for restart recovery — the missing entries get filled in on the next call because of the fast-path on lookup hit.

Errors are *pasterrors.StructuredError categorised as:

• CategoryConfig (exit 4): tracker is nil, does not implement auditDBHolder, or its auditDBHandle() returns nil; cache is nil.
• CategoryStorage (exit 5): SQLite read/write or transaction failure.
• CategoryWorkflow (exit 3): Provenance RegisterSoftwareAgent failure.

The function takes ctx for cancellation; long-running registrations (15 entries × {1 SELECT + maybe 1 RegisterSoftwareAgent + 2 INSERTs}) take well under a second on local SQLite, so context-deadline rejection is primarily about clean shutdown if the daemon is killed during startup.

func ResolveNamespace ¶

func ResolveNamespace(explicit string) (string, error)

ResolveNamespace returns the namespace to use for a `create` operation. Explicit takes precedence; an empty value falls back to DefaultNamespace.

Errors from DefaultNamespace are wrapped as CategoryValidation so that the user is prompted to supply --namespace explicitly.