v1.0 Release Notes

Plystra v1.0 Release Notes

Document Status

Field	Value
Product	Plystra
Version	v1.0
Document Type	Release notes
Status	Draft
Release Type	Stable Self-Hosted Core

1. Release Summary

Plystra v1.0 is the first stable Core release of Plystra.

This release establishes Plystra as a self-hosted identity, authorization, resource governance, and audit core for applications that need account-identity separation and explainable permission decisions.

The core model is:

User -> UserMember -> Member -> Space

The core promise is:

User logs in.
UserMember authorizes the bridge.
Member acts.
Space isolates.
Group scopes.
Permission decides.
Resource is governed.
AuditLog explains.

v1.0 is Core-focused. Console, SDK repos, plugin runtime, Data Console, templates, and Cloud are not blocking components for this release.

2. Highlights

Plystra v1.0 adds:

Ent-backed Core schema
Versioned database migrations
Core CRUD APIs
Resource Registry registration API
Authorization check API
Authorization explain API
AuditLog query API
Standard health endpoints
Structured JSON request logging
Recovery middleware
CORS configuration
Canonical request ID output
Bearer session protection for non-public Core APIs
Disabled-by-default Data Console and metrics surfaces
Docker self-hosted baseline
OpenAPI v1.0
Finance Reviewer demo cases
v1.0 readiness documentation

3. Core Model Stabilization

v1.0 stabilizes the core entities:

User
Space
Group
Member
UserMember
Role
Permission
MemberRole
RolePermission
Resource
AuditLog

User

A User is a login account.

A User does not directly own Space permissions.

UserMember

A UserMember is the binding that allows a User to act as a Member.

Revoked or expired UserMember bindings deny authorization.

Member

A Member is an in-space actor identity.

Permissions are granted to Members through Role grants.

Space

A Space is the permission and data boundary.

Group

A Group is a tree node inside a Space.

Group tree scopes use safe materialized path matching.

Resource

A Resource is a governable business object that can enter the authorization chain.

AuditLog

AuditLog records decision-time snapshots and is append-only.

4. Added Ent-backed Core Schema

v1.0 introduces Ent for the Core repository.

Ent is used for:

schema definition
generated query code
persistence modeling
database consistency
migration support

Important design rules:

UserMember is a first-class entity.
MemberRole is a first-class entity.
scope_anchor_group_id remains explicit.
Generated Ent structs are not public API contracts.
External repositories must not import core/ent.

5. Added Versioned Migrations

v1.0 includes versioned migrations.

This release includes new migrations from the latest Core alignment work:

010
011
012

These migrations complete required v1.0 Core fields, schema alignment, and clean-empty-database Ent drift closure.

Migration tooling supports:

plystractl migrate up
plystractl migrate verify
plystractl ent check

Production mode intentionally rejects unsafe Ent auto apply behavior.

Users must use versioned migrations for production upgrades.

6. Added Core CRUD APIs

v1.0 adds CRUD APIs for the stable Core entities:

Users
Spaces
Groups
Members
UserMembers
Roles
Permissions
MemberRoles
RolePermissions
Resources
AuditLogs

Supported lifecycle actions include, where applicable:

create
read
list
patch
disable
restore
revoke
archive
query

AuditLogs are read/query only.

AuditLog update and delete are intentionally not exposed.

7. Added Authorization APIs

v1.0 adds:

POST /api/v1/authz/check
POST /api/v1/authz/explain

`authz/check`

Returns a compact authorization decision.

Includes:

decision
deny_code
reason
trace_id
audit_log_id if written
request_id

`authz/explain`

Returns a full authorization trace.

Includes:

actor snapshot
space snapshot
target resource snapshot
matched candidates
scope checks
decision
deny_code
reason
audit context

8. Added Resource Registry Registration API

v1.0 adds a Resource Registry registration API.

Resources can now enter the authorization chain through:

resource_type
space_id
group_id
owner_member_id
metadata

This allows newly registered resource types to participate in:

authz/check
authz/explain
AuditLog
Permission evaluation
Scope resolution

9. Added AuditLog Query API

v1.0 adds AuditLog query APIs.

AuditLogs can be queried by:

actor_user_id
actor_member_id
actor_user_member_id
resource_type
resource_id
decision
deny_code
request_id
created_at range

AuditLog traces store decision-time snapshots.

Historical logs remain explainable even if live Role, Permission, Group, Member, or Resource records change later.

10. Added Health, Ready, and Version Endpoints

v1.0 adds standard health endpoints:

GET /api/v1/health
GET /api/v1/ready
GET /api/v1/version

`/health`

Reports basic service health.

`/ready`

Checks database and migration readiness.

`/version`

Reports version, schema version, and related build information.

11. Added Structured JSON Request Logging

v1.0 adds structured JSON request logging.

Logs include:

timestamp
level
request_id
method
path
status
latency
remote_ip
user_agent
error information when present

This improves production debugging and allows request logs to be correlated with API responses and AuditLog entries.

12. Added Recovery Middleware

v1.0 adds recovery middleware.

Behavior:

panic is recovered
safe error response is returned
request_id is included
panic is logged
stack details are not exposed to clients in production

13. Added CORS Configuration

v1.0 adds CORS configuration.

Configuration is environment-driven.

Operators should review allowed origins before production deployment.

Production mode rejects wildcard CORS origins. Use explicit origins in CORS_ALLOWED_ORIGINS.

13.1 Added Admin Token Protection

Non-public Core API routes require Authorization: Bearer <access_token> for a user with an active admin grant.

Public operational endpoints are limited to health, readiness, and version routes. Session auth endpoints use their own credential or bearer-token checks.

AuditLog, Resource Registry, Core CRUD, authorization, plugin/template management, and preview data APIs are not anonymously accessible.

Opaque bearer session tokens are stored as HMAC hashes using PLYSTRA_SESSION_SECRET.

13.2 Disabled Preview Surfaces By Default

Data Console routes and metrics are disabled by default:

DATA_CONSOLE_ENABLED=false
METRICS_ENABLED=false

Operators must explicitly enable them when needed.

14. Added Docker Self-Hosted Baseline

v1.0 includes:

Dockerfile
docker-compose.yml
.env.example
plystra-core service
postgres service

This provides a baseline self-hosted deployment path.

The Docker Compose setup is intended for:

local development
self-hosted evaluation
small deployment baseline

Production operators should review:

TLS termination
reverse proxy
PostgreSQL backups
environment secrets
audit log retention
upgrade process

15. Added OpenAPI v1.0

v1.0 updates OpenAPI documentation for the stable Core API.

OpenAPI includes:

authz/check
authz/explain
Core CRUD APIs
Resource Registry
AuditLog query
health endpoints
error envelope
request_id fields
deny code references

The OpenAPI document is the foundation for future SDK generation.

16. Added Finance Reviewer Demo

v1.0 includes the Finance Reviewer demo with four required cases.

Case	Actor	Target	Decision	Purpose
1	Alice via Finance Reviewer	Finance/APAC invoice	allow	proves group_tree allow
2	Alice via Finance Reviewer	Legal/EMEA invoice	deny `SCOPE_OUT_OF_BOUNDS`	proves scope boundary
3	Bob via same Finance Reviewer	Finance/APAC invoice	allow	proves multiple Users can share a Member
4	Alice via revoked binding	Finance/APAC invoice	deny `USER_MEMBER_REVOKED`	proves UserMember is an independent authorization bridge

17. Request ID

v1.0 returns request ID once, at the top level of the response envelope:

{
  "request_id": "req_..."
}

Core does not return meta.request_id.

18. Notes

Core Scope

v1.0 is Core-focused.

The following may exist as positive enhancements but are not release blockers:

sibling repositories
Console-related metadata
plugin metadata
early SDK preparation

Ent Auto Apply

Production mode intentionally rejects unsafe Ent auto apply behavior.

Use versioned migrations instead.

AuditLog

AuditLog is append-only.

Do not expect update or delete APIs for AuditLog.

Plugin Schema

Plugin schema extension is deferred.

Plugins must not modify Core Ent schemas or import generated Core Ent packages.

19. Breaking Changes

Document project-specific breaking changes here before final release.

Known breaking changes in the current dev line:

response envelope has one top-level request_id and no meta.request_id
operational aliases under /system/* and /api/v1/system/* are removed
top-level AuditLog route is /api/v1/audit/logs
HTTP authz accepts nested actor only
password verification accepts Argon2id hashes only

20. Upgrade Notes

Before upgrading:

backup PostgreSQL
review migration notes
stop Core service if required
apply versioned migrations
verify migrations
start Core service
run doctor
smoke test health/ready/version
smoke test authz/check and authz/explain

Recommended commands:

plystractl migrate up
plystractl migrate verify
plystractl ent check
plystractl doctor

Production operators must not use Ent auto migration as an upgrade mechanism.

21. Validation Summary

Before publishing this release, maintainers should verify:

go test ./...
PLYSTRA_DATABASE_URL=... go test ./...
plystractl migrate up
plystractl migrate verify
plystractl ent check
plystractl doctor
production ent apply rejection
Finance Reviewer four demo cases
health/ready/version
authz/check
authz/explain
Resource Registry
Core CRUD APIs
AuditLog query
OpenAPI route consistency
Docker Compose quickstart

22. Known Limitations

v1.0 does not include:

full Console
full Data Console
official SDK GA
plugin runtime GA
plugin marketplace
template installer
Cloud hosting
enterprise SSO
advanced policy language
workflow engine
storage service
realtime service
serverless functions

These are planned for later versions.

23. Recommended Next Version Focus

After v1.0, recommended priorities are:

v1.1 Core hardening
v1.2 SDK and integrations
v1.3 Data Console GA
v1.4 First-party plugins
v1.5 Templates GA
v1.6 Production self-hosting

Do not start all of these at once.

24. Final Statement

Plystra v1.0 is not stable because it has many features.

It is stable because the Core model is consistently implemented:

User logs in.
UserMember authorizes the bridge.
Member acts.
Space isolates.
Group scopes.
Permission decides.
Resource is governed.
AuditLog explains.

All future features should strengthen this model rather than dilute it.