@haneinfo/plugin-api
Framework-neutral plugin manifests, capabilities, and lifecycle contracts. The lifecycle runner
is available from @haneinfo/plugin-api/runtime.
Cooperative lifecycle cancellation
The runner supplies an optional context.signal to every lifecycle hook. Existing context
objects and hooks remain valid. Each invocation receives a fresh signal, including shutdown.
Pass the signal to cancellable I/O, check it before acquiring resources, and join all initialization/cancellation child work before the hook settles. Hooks must not
detach initialization promises that can acquire resources later. Long-lived background work
started in ready must have a shutdown owner that stops and joins it before resource teardown.
import type { PluginLifecycleHooks } from '@haneinfo/plugin-api';
const lifecycle: PluginLifecycleHooks = {
async register(context) {
try {
context.signal?.throwIfAborted();
await connectResources({ signal: context.signal });
context.signal?.throwIfAborted();
await registerSubscriptions({ signal: context.signal });
} catch (error) {
await releasePartialResources();
throw error;
}
},
async shutdown(context) {
// Must tolerate missing or already-released resources.
await releaseResources({ signal: context.signal });
},
};
These resource functions are application-specific. A startup hook's promise must cover its acquisition,
cancellation, and partial cleanup; settling a promise is the runner's boundary for safe teardown.
Use finally where appropriate. Shutdown must be idempotent and tolerate partial registration.
A boot-stage timeout requests cancellation and aborts startup, even for an optional instance.
An optional hook that settles with an ordinary error keeps its manifest's degradation policy.
Direct runner callers must call shutdown() after an aborted boot. The Nest host does this
automatically when initialization fails; it does not depend on a later app.close().
Shutdown waits for an in-flight boot hook before invoking that instance's cleanup or tearing down previously started providers. The existing per-instance shutdown budget bounds that wait and its cleanup. If the hook outlives this budget, shutdown returns a report and resumes reverse-order cleanup automatically once the hook settles. A validation hook that never reached register is waited for but does not receive a shutdown invocation. Concurrent/repeated shutdown calls do not invoke a cleanup hook again. The existing policy of reporting a timed-out shutdown hook and continuing with the remaining instances is preserved.
HostShutdownResult preserves the existing outcome strings and adds pendingCleanup and
diagnostics. A nonempty pendingCleanup means resources have not been confirmed released;
shutdown-completed-with-reported-timeout means the reporting pass ended, not that all hooks
stopped. Catalog entries expose cleanupPending. runner.cleanupDiagnostics and the Nest catalog
refresh pending diagnostics as late cleanup settles. Returned shutdown results and lifecycle
events are snapshots/history; a historical timeout remains reported after eventual cleanup.
Signals cannot forcibly stop JavaScript. A legacy hook that ignores cancellation may continue
acquiring resources until it settles; deferred cleanup waits for that settlement. A hook that
never settles, blocks the event loop, or detaches work cannot be safely stopped in this process.
Startup remains failed and the owning process/supervisor must terminate that process when cleanup
cannot finish. The library does not call process.exit() or terminate the host itself.
The harness interface keeps the new report fields optional in its types so existing test doubles that return only outcome/events still compile. The actual runner and harness always provide both.
The cancellation-aware host and testkit require plugin-api ^1.5.0. Their release must include
the matching plugin-api minor; this does not require changing existing hook signatures.
Numbering contracts
NUMBERING / haneinfo.numbering bind NumberingPort.allocate({ scope, at }, tx). The caller
must supply the submission transaction; providers must not commit or allocate independently.
Only state-machine transitions use this port. The runtime's optional queryNumberedFor method
provides authorized, bounded read-only lookup to the state-machine MCP tools.
Definition kinds may implement validatePublishedChange(previous, next) to preserve invariants
after publication. The definition registry applies it to runtime draft writes, publishing and repo
sync. Metadata.code remains immutable under the existing generic registry rule.
Background jobs and instance list contracts
BACKGROUND_JOBS / haneinfo.background-jobs bind BackgroundJobsPort: register typed handlers,
enqueue with an authenticated creator and read/cancel only that creator's jobs. Handlers receive
an independent attempt transaction, progress callback, cancellation checkpoint and AbortSignal.
Producers declare the capability in requires; do not instantiate another worker module.
LIST_VIEW / haneinfo.list-view bind ListViewPort.queryFor and batchesFor. Query input is
validated at the provider, and every page applies instance authorization in the database.
The bounded batch interface is a live scan for future exports; it does not create files or promise
a frozen cross-page snapshot. These contracts do not depend on the provider packages or Form.
Bounded identity picker search
IdentityStorePort optionally exposes searchActiveByName({ q, excludeId, afterId?, limit }, transaction?). Providers return only id/name for active identities, with case-insensitive name containment, id keyset ordering and a maximum page of 20. Consumers must separately enforce instance readership. Older providers remain structurally compatible; a feature needing search must fail closed when absent. identity-core implements it and collaboration consumes it. The optional addition is queued as a minor release; PLUGIN_API_VERSION remains synchronized with the current package version until the maintainer runs the release version step.
Optional batch identity names
IdentityStorePort.findActiveNamesByIds?(ids, transaction?) resolves authorized page/batch submitter ids to active { id, name } rows. Missing/inactive/deleted ids are omitted; older providers remain compatible. InstanceListItem.submitterName is nullable. StateMachineInstanceView.submitterName is optional because trusted internal snapshots and older runtimes do not supply display metadata; authorized public state-machine reads always supply string or null. Public consumers render names as text and MCP wraps them as $userContent.
PLUGIN_API_VERSION and the package version are 1.12.0. Affected plugin manifests accept ^1.12.0; the optional method is feature-detected so an older provider remains usable.
Optional period delegation
DelegationResolverPort resolves one-hop (delegatorId, delegateId, delegationId) matches for original assignee IDs, assignment code and time, and validates a recorded delegation at response time. DELEGATION_RESOLVER maps to haneinfo.delegation-resolver. The optional internal Assignment effects registration joins the caller transaction for immediate backfill and revocation without a capability dependency cycle. ASSIGNMENT trigger attribution adds optional actingUserId and onBehalfOfId. The 1.13.0 contract is advertised by PLUGIN_API_VERSION while package.json awaits its pending minor changeset; the version test requires that changeset whenever the contract leads by one minor.
When the resolver is installed, StateMachine takes its optional shared transaction advisory lock before instance creation or any instance row lock/write. Delegation creation/revocation takes the exclusive lock on the same key. Normal instance transactions remain concurrent; a graph mutation briefly blocks new instance writers until its backfill/cancellation commits. This closes the race where creation and state entry could otherwise miss each other's uncommitted rows. The advisory lock always precedes instance locks; task CAS and delegation-row shared locks remain inside that transaction. No extra table or worker is added.
Instance access lists (draft implementation)
Implemented against draft decision 202610-c8e3; the decision remains draft.
API 1.14.0 adds optional RbacPolicyPort.findRolesByNames(names, transaction?), returning existing {name, displayName: string | null} entries. Older providers remain structurally compatible. Without the method, state-machine rejects role grants and returns null role labels. Existing rolesForUser and PrincipalAuthorization.roleNames support role expansion without a new port. New method consumers (state-machine and RBAC) require API 1.14.0; unrelated manifest engine floors remain unchanged.
Upgrade the affected mechanisms together after applying the App migration. The maintained model, HTTP routes, read-only list_instance_access MCP tool, errors and permission contract are documented in @haneinfo/state-machine/agent-guide.md. Its prisma/instance-access.sql migrates the existing reader table to USER/ROLE, READ/WRITE and ASSIGNED/DELEGATED/GRANTED rows while retaining timestamps. The maintainer selected (instanceId, principalType, principalId, source) uniqueness. Manual grants are limited to 100 by default; permanent READ entries survive manual removal. See the package repository validation/equipment-loan/instance-access/report.md for SQL, tests and App restoration evidence.
Optional streaming files (API 1.15.0)
FileStoragePort / FILE_STORAGE / haneinfo.file-storage provides put(key, Readable, options) returning actual bytes, get(key) returning Readable, delete and exists. AttachmentScannerPort / ATTACHMENT_SCANNER / haneinfo.attachment-scanner optionally returns CLEAN or REJECTED(reason) from a stream and metadata. Implementations must keep content streaming and release streams on failure. No presigned/public URL contract is provided. The runtime version leads package.json by one minor until its pending minor changeset is released.
Instance lifecycle (draft 202610-f1a8)
Implemented from draft decision 202610-f1a8; the decision remains draft. Upgrade state-machine, list-view, collaboration, attachments, import-export, assignment and timer together. No frontend, automatic archive or bulk lifecycle operations are included. Permanently purged data cannot be restored by this API: database and private file backups must cover the entire deletion retention period and be restored consistently.
API 1.16.0 adds optional archived/archivedAt to StateMachineInstanceView and optional archived to InstanceListItem so older providers and consumers remain compatible. Lifecycle-aware runtime and list-view providers always populate them. Only state-machine and list-view raise their manifest engine minimum to 1.16.0. Events use the existing MechanismEvent envelope and string names; no new capability, token, event bus or lifecycle mutation port is introduced.
Instance tags (contract 1.17.0)
The pure normalizeInstanceTag/normalizeTagText helpers and exported valid/invalid vector corpus are shared by writes and list filters. InstanceTagsPort / INSTANCE_TAGS / haneinfo.instance-tags optionally supplies maxTagLength and one labelsFor query per authorized page. InstanceListItem.tags is optional for older providers; new list-view always returns an array. See tags/README.md for normalization, Unicode case expansion and inherited authorization.
Draft data preparation (202610-8b3e)
Draft implementation; the decision remains draft. Contract 1.18.0 adds optional PrepareDataOptions (requireRequired?: boolean) to DefinitionKindRegistration.prepareData and DefinitionRegistryPort.prepareData. Omission retains full validation. StateMachineInstanceView optionally exposes fieldRevisions with removed-field tombstones; older providers can omit it. No new capability, MCP write tool or runtime port method is added. MechanismError.toJSON retains details.currentRevision, bounded conflicts and retryAfterSeconds without a new error envelope. Upgrade the registry forwarder and Form consumer together with state-machine; their manifests require 1.18.0.
Unified search (contract 1.19.0, draft 202610-a3d8)
Draft implementation; the decision remains draft. SearchPort / SEARCH / haneinfo.search
offers searchFor, reindexFor and statusFor, each authorizing the caller. SEARCH_PROVIDERS is not
a capability: it resolves to the optional SearchProviderRegistry (limits, register) exported
by @haneinfo/search; Nest has no multi-provider tokens, so contributors inject it with @Optional()
and register one SearchProvider (source, events, documentFor(instanceId, tx)) per source.
Every provider must build rows with the shared composeSearchBody / truncateSearchText and match
with normalizeSearchText (NFKC, lowercase, whitespace folding, controls as spaces, format
characters removed, applied per base character so normalizeSearchTextWithMap maps back to the
original). SEARCH_NORMALIZATION_TEST_VECTORS is the shared corpus. Constants cover sources,
weights, default limits, SEARCH_ADMIN_PERMISSION (search:search:admin), SEARCH_READ_SCOPE
(search:read) and the new STATE_MACHINE_START_RECORDED event name.
Instance analytics (contract 1.28.0, rename decision 202610-fed6)
CAPABILITY.instanceAnalytics and INSTANCE_ANALYTICS identify the renamed capability.
CAPABILITY.reports and REPORTS remain deprecated until the next major; no manifest provides
the old capability. The report domain contract introduced in 1.20.0 is unchanged.
Draft implementation; the decision remains draft. ReportsPort / INSTANCE_ANALYTICS / haneinfo.instance-analytics
(optional capability, provided by @haneinfo/instance-analytics) offers fieldsFor, queryFor,
stateDurationsFor and saved-report CRUD (createFor, listFor, getFor, updateFor, deleteFor,
shareFor, runFor); every method authorizes the caller. Types cover aggregate queries (measures with
count/sum/avg/min/max, groupBy with $createdAt buckets, list-view filters, archived,
orderBy, limit), state-duration queries, results, display hints and saved reports. Constants cover
REPORT_ERROR_CODES (REPORT_QUERY_INVALID, UNDECLARED_REPORT_FIELD, REPORT_TIMEOUT,
REPORT_NOT_FOUND), the built-in dimensions and $leadTime, measure ops, time buckets, chart types,
visibilities, defaults and the MCP scope suffixes REPORTS_READ_SCOPE (reports:read) and
REPORTS_WRITE_SCOPE (reports:write). reportBucketStart is the reference for local
Monday-based buckets; REPORT_BUCKET_TEST_VECTORS is the shared corpus the SQL must agree with.
Data change log source (contract 1.21.0, draft 202610-d9a5)
Draft implementation; the decision remains draft. StateMachineRuntimePort.start accepts an
optional source (CREATE by default, or IMPORT) that labels the creating write in the
instance data change log of @haneinfo/state-machine. Import adapters pass IMPORT; older runtimes
ignore the field. No new capability, token or scope is added. The diff format itself lives in the
pure library @haneinfo/diff, not in this contract.
Settings and feature flags (contract 1.22.0, draft 202610-e6c1)
Draft implementation; the decision remains draft. SettingsPort / SETTINGS /
haneinfo.settings (optional capability, provided by @haneinfo/settings) offers system reads:
get (value, source OVERRIDE/STATIC/DEFAULT, revision), value, evaluateFlag and isEnabled.
SETTING_DECLARATIONS is not a capability: it resolves to the optional
SettingDeclarationRegistry (register(...declarations)), injected with @Optional() like
SEARCH_PROVIDERS. SettingDeclaration covers code, kind (setting or flag), description, type
(boolean, integer, number, string, enum, stringList), default, constraints (min, max, values,
pattern, maxItems, maxLength), staticRef and knownItems; validateSettingDeclaration refuses
unknown or sensitive properties and secret-looking codes, and validateSettingValue applies the
constraints and the hard caps (2,000 code points per string, 200 list entries) and normalizes a
boolean flag value to { enabled }. evaluateSettingFlag applies denyUsers → allowUsers →
allowRoles → percent → enabled; settingFlagBucket is the stable FNV-1a bucket of
<code>:<userId> and SETTING_FLAG_BUCKET_TEST_VECTORS the shared corpus. Constants cover
SETTING_ERROR_CODES (SETTING_NOT_FOUND, SETTING_INVALID, SETTING_REVISION_CONFLICT,
SETTING_PROPOSAL_NOT_FOUND, SETTING_PROPOSAL_NOT_PENDING), sources, statuses, change sources,
proposal statuses, SETTINGS_CHANGED_EVENT, the permissions settings:setting:read and
settings:setting:write, and the MCP scope suffixes settings:read and settings:propose.
Object references (contract 1.23.0, draft 202610-f7a2)
Draft implementation; the decision remains draft. ReferencesPort / REFERENCES /
haneinfo.references (optional capability, provided by @haneinfo/references) offers listFor,
graphFor, createFor, removeFor and the system cleanup removeAllFor. OBJECT_TYPE_PROVIDERS and
LINK_KINDS are not capabilities: they resolve to the optional ObjectTypeProviderRegistry and
LinkKindRegistry, injected with @Optional() like SEARCH_PROVIDERS. An ObjectTypeProvider has a
type and batched readableIds, writableIds and previewFor (cards { type, id, title, subtitle?, state?, stateLabel?, archived?, path }), plus optional recordLinkActivity and
onPermanentlyRemoved. ObjectRef is { type, id }; parseObjectRef / formatObjectRef handle the
<type>:<id> form (type: lowercase hyphenated words up to 64; id: 1–128 code points without
whitespace, control or format characters) and OBJECT_REF_TEST_VECTORS is the shared corpus.
BUILT_IN_LINK_KINDS (relatesTo symmetric, derivedFrom, blocks, supersedes) and
validateLinkKindDeclaration cover kinds. Constants cover REFERENCE_ERROR_CODES (LINK_INVALID,
LINK_KIND_UNKNOWN, OBJECT_NOT_FOUND, LINK_LIMIT_EXCEEDED, LINK_NOT_FOUND, FORBIDDEN),
STATE_MACHINE_INSTANCE_OBJECT_TYPE, the events references.linked / references.unlinked, the
permission references:link:admin, the MCP scope suffixes references:read and
references:write, and the default limits.
Spaces and inherited access (contract 1.24.0, draft 202610-b1d6)
Draft implementation; the decision remains draft. SpacesPort / SPACES / haneinfo.spaces
(optional capability, provided by @haneinfo/spaces) offers listSpacesFor, getNodeFor, childrenFor,
createSpaceFor, createFolderFor, updateNodeFor, deleteNodeFor, accessFor, putAccessFor,
removeAccessFor, placeFor, unplaceFor and instancesFor, each authorizing the caller. Types cover
nodes (SPACE / FOLDER, SpaceNodeView with the caller's access and canManage), breadcrumbs,
access entries (USER / ROLE, READ / WRITE / MANAGE), effective access with viaNodeId,
placements ({ object: ObjectRef, nodeId, placedBy, placedAt }) and instance list pages. The pure
helpers effectiveSpaceAccess (own entries plus the parent's effective access while inheritAccess
is true, highest level per principal, nearest node on ties), spaceAccessLevelFor,
spaceAccessAtLeast, inheritedInstanceLevel / inheritedInstanceAccess (MANAGE becomes instance
WRITE) and normalizeSpaceName come with the shared SPACE_ACCESS_TEST_VECTORS and
SPACE_NAME_TEST_VECTORS. INSTANCE_ACCESS_SOURCES adds INHERITED (INHERITED_ACCESS_SOURCE) to
ASSIGNED, DELEGATED and GRANTED. Constants cover SPACE_ERROR_CODES (SPACE_NODE_NOT_FOUND,
SPACE_INVALID, SPACE_NAME_TAKEN, SPACE_NOT_EMPTY, SPACE_TOO_LARGE, SPACE_DEPTH_EXCEEDED, FORBIDDEN),
the events spaces.placed and spaces.access-changed, the permissions spaces:space:create and
spaces:space:admin, the MCP scope suffix spaces:read and the default limits (depth 8, 500
children, 5,000 affected instances, names of 200 code points, pages of 50 up to 200).
Generated MCP read tools (contract 1.25.0, draft 202610-c5e8)
Draft implementation; the decision remains draft. McpGeneratedToolsPort / MCP_GENERATED_TOOLS /
haneinfo.mcp-generated-tools (optional capability, provided by @haneinfo/mcp-generated-tools)
offers diagnosticsFor(userId) (permission mcp-generated-tools:tools:read) returning
McpGeneratedToolsDiagnostics with McpGeneratedToolDescriptor and McpGeneratedToolSkip entries.
Constants cover MCP_GENERATED_TOOL_KINDS (list, get, search, report),
MCP_GENERATED_TOOL_ERROR_CODES (UNKNOWN_FIELD, INVALID_INPUT, FORBIDDEN, INSTANCE_NOT_FOUND),
MCP_GENERATED_SKIP_REASONS (NAME_CONFLICT, NAME_TOO_LONG, MACHINE_LIMIT, SCHEMA_TOO_LARGE,
MISSING_DECLARATION, MECHANISM_UNAVAILABLE), MCP_GENERATED_WARNING_CODES (COLUMNS_ENUM_OMITTED), the
defaults (60 s refresh, 20 machines, 32 KB schemas, 32-character name fragments), label limits and
MCP_TOOL_NAME_MAX_LENGTH (64). Pure helpers: mcpGeneratedToolNameFragment /
isMcpGeneratedToolNameFragment / mcpGeneratedToolName (with MCP_GENERATED_NAME_TEST_VECTORS),
mcpGeneratedScalarSchema / mcpGeneratedFilterSchema / mcpGeneratedComparisonOperators (the
JSON Schema of each field type, pinned by MCP_GENERATED_FILTER_SCHEMA_TEST_VECTORS),
mcpGeneratedUserText and mcpGeneratedFieldDescription (labels as cleaned, bounded, quoted user
content). McpToolSourcePort and the optional McpToolsPort.registerToolSource /
refreshToolSources describe runtime-changing tool sources (mcp-server 3.4);
StateMachineRuntimePort.getFor is the optional user-authorized instance read.
Localized labels and state tones (contract 1.26.0, draft 202610-a8d3)
Draft implementation; the decision remains draft. LocalizedText is a plain string or a map from a
supported locale to a non-empty string, e.g. { "zh-TW": "借用人", "en": "Borrower" }.
SUPPORTED_LOCALES is ['zh-TW', 'en'] and DEFAULT_LOCALE is zh-TW. localizeText(text, locale?) returns one string: the requested locale, then zh-TW, then en, then the first available
value; a string is returned as is and an empty map gives ''. localizedTextValues lists every
distinct translation (for indexing). localizedTextJsonSchema({ minLength?, maxLength }) is the
schema fragment definition kinds embed (strings keep their previous limits; maps need at least one
supported locale with 1–maxLength code points); localizedTextIssues / isLocalizedText check the
same rules plus whitespace-only map values. Requests: parseLocale (case-insensitive whitelist),
localeFromAcceptLanguage (quality order; en* gives en, zh* gives zh-TW; bounded) and
resolveRequestLocale({ query, acceptLanguage }) (an explicit ?locale= must be zh-TW or en, else
INVALID_LOCALE/400; then Accept-Language; then zh-TW). Shared vectors: LOCALIZE_TEXT_TEST_VECTORS,
LOCALIZED_TEXT_ISSUE_TEST_VECTORS, LOCALE_RESOLUTION_TEST_VECTORS.
StateTone is one of STATE_TONES (neutral, info, success, warning, danger);
DEFAULT_STATE_TONES maps INITIAL and FINAL to neutral, NORMAL and CHOICE to info, and
stateToneOf(state) returns a valid declared tone or the type default (neutral for anything else,
STATE_TONE_TEST_VECTORS). InstanceListItem and StateMachineInstanceView gain optional
stateLabel and stateTone (display metadata of public reads); StateMachineRuntimePort.getFor
accepts an optional { locale }.
IAM profile and token time contracts (contract 1.29.0)
IAM_PROFILE (CAPABILITY_IAM_PROFILE / haneinfo.iam-profile) and IAM_TOKEN_EXCHANGE
(CAPABILITY_IAM_TOKEN_EXCHANGE / haneinfo.iam-token-exchange) define the backend IAM profile
and outbound token-exchange ports (IamProfilePort, IamTokenExchangePort,
TokenExchangeProvider, IamDeploymentConfig, IamCapabilityAssessment, and normalized claims by
IamTokenUse). validateTokenTimestamps and TOKEN_TIME_TEST_VECTORS share the iat/exp
timestamp rules across @haneinfo/oidc-auth and @haneinfo/mcp-server. See
specs/topics/iam-contract.md for the full specification.